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

21–30 of 74 posts

Re: Write OpenAPI with TypeSpec

#21

Post by Stoids »

I like the idea, especially the TS-like syntax around enums and union types. I've always preferred the SDL for GraphQL vs writing OpenAPI for similar reasons. Most APIs I've run into in my career would benefit from modeling their API responses as ADTs versus the usual approach of overloading 4 different union members into a giant spare object.

I echo the sentiment others have brought up, which is the trade-offs of a code-driven schema vs schema-driven code.

At work we use Pydantic and FastAPI to generate the OpenAPI contract, but there's some cruft and care needed around exposing those underlying Pydantic models through the API documentation. It's been easy to create schemas that have compatibility problems when run through other code generators. I know there are projects such as connexction[1] which attempt to inverse this, but I don't have much experience with it. In the GraphQL space it seems that code-first approaches are becoming more favored, though there's a different level of complexity needed to create a "typesafe" GraphQL server (eg. model mismatches between root query resolvers and field resolvers).

[1] https://github.com/spec-first/connexion

Re: Write OpenAPI with TypeSpec

#22

Post by Petermarcu »

lijok wrote: post #17
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…

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

Agreed. If the schema can also generate the service routes, models, serialization, etc, and you just have to maintain the business logic in the service, you get the spec matches the service benefits that way as well. Best of both worlds? People using gRpc seem to be 100% fine with schema first and generating the service stubs.

One of the key things with having the spec is that you can actually describe a lot more than you can with the various attributes and comments in the code. Especially things that are not as much service concerns but potentially client concerns or documentation concerns. You can also encapsulate reusable API patterns so you know different operations are following the same pattern.

The author didn't go into all the details but there are lots of ways in TypeSpec to separate the concerns of different consumers of the spec. There is a lot of opportunity and creative thinking that can be done here.

Re: Write OpenAPI with TypeSpec

#23

Post by henry_pulver »

Great idea - spend far too long reading & writing OpenAPI!

Particularly anyOf, allOf and oneOf (especially when nested) lead to really confusing nested specifications in OpenAPI. Really like how TypeSpec handles unions & intersections.

Playground is great for getting a feel for it fast too

Re: Write OpenAPI with TypeSpec

#24

Post by mnahkies »

lijok wrote: post #17
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…

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

Yeah I'm also on the schema first side of the debate.

I think for me it comes down to a few key points:

- APIs are forever, the choice of language/framework is an implementation detail

- Constraining yourself to what can be represented in the specification is better than generating a specification from implementation that may not be capable of expressing the full details

- When working with diverse languages it provides a common ground/language for discussing API changes. Eg: if you have java backend, kotlin android, swift iOS, react/whatever web you can bring everyone together with the spec

- Subjective, but a good spec will include a bunch of documentation and examples that tend to create a lot of noise in the code. I personally prefer to keep this in the spec and the implementation smaller

I think the main counterpoint to this is that you can generate the spec and then take that and change your mind if you later change language/framework etc - it's not a one-way door.

My biggest bug bear is that regardless of spec first or implementation first, you should have something you write once and generate the rest of the glue from (eg: docs, client sdks). Writing each piece manually/independently always leads to drift and bugs.

(I'm working on my own little openapi -> typescript code generator over here https://github.com/mnahkies/openapi-code-generator - eventually plan to support more than typescript, and adding typespec support is something I'm currently considering)

Re: Write OpenAPI with TypeSpec

#25

Post by dz0707 »

tyayers wrote: post #2

This is typical Microsoft - overly complicated solution in search of a problem. Yaml and Json are beloved for a reason - they're simple and effective.

Having written quite a bit of open API specs, I don't agree with you. Json is hard to read, yaml has own quirks, especially when you try to spilt it into parts. Amazon also tries to invent own language for describing apis, so I guess they are not happy with open API too. Anyway, without ability to generate code from spec, there is not much use from it. Code gen/nswagger/open API generator and others produce terrible code, at least for java/c#/typescript(there's 4.1k open issues for open API generator), using custom generators for codegen make problem less painful, but that is additional burden, I'm looking for better alternative, would be very interesting to see what they will do with code generation.

Re: Write OpenAPI with TypeSpec

#26

Post by mooreds »

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)?

Re: Write OpenAPI with TypeSpec

#27

Post by alecthomas »

tyayers wrote: post #2

This is typical Microsoft - overly complicated solution in search of a problem. Yaml and Json are beloved for a reason - they're simple and effective.

I would be absolutely stunned if anyone, ever, has described OpenAPI as "beloved". It does its job, but that's about the best you can say about it.

Re: Write OpenAPI with TypeSpec

#28

Post by bterlson »

mnahkies wrote: post #24
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.

Yeah I'm also on the schema first side of the debate. I think for me it comes down to a few key points: - APIs are forever, the choice of language/framework is an implementation detail - Constraining yourself to what can be represented in the specification is better than generating a specification from implementation that may not be capable of expressing the full details - When working with diverse languages it provi…

Hey, nice work on openapi-code-generator, its output is very nice. I think you could probably package it up as a TypeSpec emitter without too much difficulty, by emitting OpenAPI and feeding it to your generator. I am doing a similar thing for a Kiota emitter I'm working on. We recently added an API to get the OpenAPI as a JS object which may be of help in this quest:

https://typespec.io/docs/libraries/openapi3/reference/js-api...

Re: Write OpenAPI with TypeSpec

#29

Post by bterlson »

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!

Re: Write OpenAPI with TypeSpec

#30

Post by bterlson »

dz0707 wrote: post #25
tyayers wrote: post #2

This is typical Microsoft - overly complicated solution in search of a problem. Yaml and Json are beloved for a reason - they're simple and effective.

Having written quite a bit of open API specs, I don't agree with you. Json is hard to read, yaml has own quirks, especially when you try to spilt it into parts. Amazon also tries to invent own language for describing apis, so I guess they are not happy with open API too. Anyway, without ability to generate code from spec, there is not much use from it. Code gen/nswagger/open API generator and others produce terrible…

Codegen is coming online as we speak. We do codegen from TypeSpec in Azure across multiple languages, and the results are pretty great. We're moving that over to the TypeSpec project so everyone can generate code. Obviously my opinion is biased, but I think the results are significantly better than what you find elsewhere in the ecosystem.
Post reply on HN