Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Write OpenAPI with TypeSpec

blog.trl.sn

Post reply on HN
Print view View original

61–70 of 74 posts

Re: Write OpenAPI with TypeSpec

#61

Post by bterlson »

FourOnTheFloor wrote: post #60
bterlson wrote: post #57

Earlier quoted context omitted.

By the way, you can use the "allOf hack" to put documentation alongside a ref. TypeSpec emits this for common cases like this one: https://typespec.io/playground?c=bW9kZWwgRm9vIHsNCiAgLyoqIHR...

Hadn't heard of that, thanks. Does TypeSpec have description fields? I don't think I've seen any in the examples.

The playground I posted has a description. They're pulled from JSDoc style comments. You can also use the `@doc` decorator, though that's usually reserved for more advanced cases like when you need string interpolation or something.

Re: Write OpenAPI with TypeSpec

#62

Post by kkukshtel »

This project seems really interesting, I'm surprised this is the first time I'm hearing about it. Like another commenter here I'm also surprised to see no mention of Cue (or now Apple's Pkl). Is this meant to be something similar to those?

Also given it's a MS project, would love for there to be some drop in NuGet package for C# use. All these data description languages are really interesting but the fact none of them have a C ABI or only work in the language of choice seems to limit how useful they can be outside of their original context.

Re: Write OpenAPI with TypeSpec

#63

Post by [deleted] »

mdasen wrote: post #11

As someone who has used JAX-RS (Java) and ASP.NET, APIs are basically created with these kinds of annotations right in the language. @GET public Character getCharacter(@PathParam("id") int id) { return db.getCharacter(id); } That's very similar to TypeSpec's op getCharacter(@path id: safeint): Character; Java and C# classes already have the type information that you'd be getting from a TypeSpec: // TypeSpec model Cha…

[deleted]

Re: Write OpenAPI with TypeSpec

#64

Post by drewda »

When I first saw TypeSpec, I was interested in it as a way to have a single-source-of-truth for both OpenAPI and GraphQL schemas... but unfortunately though the readme mentions GraphQL, the team at Microsoft didn't actually get around to adding support to output GraphQL schemas.

Re: Write OpenAPI with TypeSpec

#65

Post by _w1tm »

sroussey wrote: post #48
lijok wrote: post #17

Earlier quoted context omitted.

This is the code-first vs schema-first debate. Both have their pros and cons. Personally a die hard advocate of schema-first.

Code first for prototyping and early stage. Then switch as soon as you have customers.

Sounds reasonable.

In an org where the customers are internal teams it makes more sense to sit down together and define a schema first. Then the consumer and provider teams just go away and write the code concurrently without having to waste time talking to each other.

Re: Write OpenAPI with TypeSpec

#66

Post by sroussey »

_w1tm wrote: post #65
sroussey wrote: post #48

Earlier quoted context omitted.

Code first for prototyping and early stage. Then switch as soon as you have customers.

Sounds reasonable. In an org where the customers are internal teams it makes more sense to sit down together and define a schema first. Then the consumer and provider teams just go away and write the code concurrently without having to waste time talking to each other.

In this case, write mock data first

Re: Write OpenAPI with TypeSpec

#67

Post by nonethewiser »

dheerajvs wrote: post #59

How does TypeSpec compare with Bru[0], the DSL used by Bruno? Why would I choose one over the other? [0] https://docs.usebruno.com/bru-lang-overview.html

Bru is a DSL for actual requests (plus other things like js). This actually made me think of Bru too but I don’t think there’s really any overlap.

Compare Bru to OpenAPI or json schema. Its just kinda non sensical.

Re: Write OpenAPI with TypeSpec

#68

Post by FourOnTheFloor »

bterlson wrote: post #61
FourOnTheFloor wrote: post #60

Earlier quoted context omitted.

Hadn't heard of that, thanks. Does TypeSpec have description fields? I don't think I've seen any in the examples.

The playground I posted has a description. They're pulled from JSDoc style comments. You can also use the `@doc` decorator, though that's usually reserved for more advanced cases like when you need string interpolation or something.

Thanks. I don't see any in that playground though. Which document are they in? I think I looked in all the ones in the drop-down.

Re: Write OpenAPI with TypeSpec

#69

Post by mooreds »

bterlson wrote: post #29
mooreds wrote: post #26

As someone who wrote a custom dsl to Open API spec script (in Ruby) I'm really interested to see if type spec would be a better output. Our spec is > 12k lines and we haven't even included everything that needs to be defined. Does anyone have experience layering this on to an existing API (as opposed to defining the API and then building the code)?

Extensive experience inside Azure. In general, supporting existing APIs is harder, predominantly because it might not sufficient to produce a semantically identical OpenAPI when downstream tools are sensitive to e.g. whether something is a ref or not, the order of properties in the document, whether something uses `const` or an `enum` with a single member, etc. If you have more specific questions I'm happy to consult…

Haha, thanks for the reply! We're spending some time this quarter working on our open API spec and have engaged some experts, but if we need more help, I know who to reach out to!

Re: Write OpenAPI with TypeSpec

#70

Post by bterlson »

FourOnTheFloor wrote: post #68
bterlson wrote: post #61

Earlier quoted context omitted.

The playground I posted has a description. They're pulled from JSDoc style comments. You can also use the `@doc` decorator, though that's usually reserved for more advanced cases like when you need string interpolation or something.

Thanks. I don't see any in that playground though. Which document are they in? I think I looked in all the ones in the drop-down.

The link should load up with a sample I wrote, I think? It does for me anyway! Let me know if you don't see it. But I'll also paste it here:

    model Foo {
      /** this is a description */
      x: Bar;
    }

    /** this is also a description */
    model Bar {}
Post reply on HN