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

51–60 of 74 posts

Re: Write OpenAPI with TypeSpec

#51

Post by seer »

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 also schema-first here. I think this is the “easy vs simple” debate all over again.

Writing code first schema is very easy, but when you start _using_ that api as part of a greater system is where the approach starts falling short.

Schema first allows for great communication between teams - one team requires changes to an api service, they can hash it out with the api, and then go back and implement both the client _and_ server simultaneously.

The great benefit here is the inevitable back-and forth can be done together, as each side might need to adjust the api while they are implementing the client/server as often happens with engineering efforts. And thats a lot easier to do while each side is working on it rather than the usual one side is “done” and moves to another task and needs to go back and modify.

In fact at the time I built quite a nice system of generating typescript types for both client and server - https://github.com/ivank/laminar

I guess because the project tried to introduce strong typing and fp style to node http servers plus a few other ideas stolen from here and there, it tried to do too much and never really got traction.

Re: Write OpenAPI with TypeSpec

#53

Post by nonethewiser »

I find it kind of discouraging that we now need a language to define an API that compiles into OpenAPI but honestly I hate writing OpenAPI specs (especially compared to gql).

So despite thinking it’s kinda dumb, Im all ears. Halfway through the article and it seems compelling so far.

Re: Write OpenAPI with TypeSpec

#54

Post by FourOnTheFloor »

Targeting OpenAPI 3.0 is a bad idea. It wasn't until 3.1 that it became truly useful, if only because it fixed one glaring blunder: Pre-3.1, you inexplicably couldn't provide a description along with a $ref. This defeats one of the major purposes of OpenAPI, which is... documenting your API.

Example: If you define a structure called Rectangle and use it all over the place, you can't say what this rectangle means or that rectangle means when the structure is used in your API. How was that ever deemed acceptable? Widespread use of common structures (which one would certainly expect in a well-designed API) resulted in an API that couldn't be documented in OAS.

The OpenAPI code-generation landscape is truly abysmal. Not only do almost none of the tools support version 3.1 (which has been current for years), but the generators themselves are of widely varying (but mostly shitty) quality and scattered across a couple of apparent major repos. The documentation is likewise a confusing morass of conflicting and incomplete information from several sources. I flailed away trying to fix one generator for weeks, or write a new one. But I couldn't even find a concise list of the data structures offered to the template engine after an OpenAPI doc is ingested by OpenAPIGenerator. Isn't that a fundamental part of creating a new generator?

So it raises the question of whether OpenAPI is salvageable, or whether this new DSL is better... from design to code generation. Given the trashy state of OpenAPI code generators, why bother generating OAS at all? Just move on and write some competent generators using this new language.

Re: Write OpenAPI with TypeSpec

#55

Post by bterlson »

FourOnTheFloor wrote: post #54

Targeting OpenAPI 3.0 is a bad idea. It wasn't until 3.1 that it became truly useful, if only because it fixed one glaring blunder: Pre-3.1, you inexplicably couldn't provide a description along with a $ref. This defeats one of the major purposes of OpenAPI, which is... documenting your API. Example: If you define a structure called Rectangle and use it all over the place, you can't say what this rectangle means or t…

For what it's worth, we support 3.0 because as you note the ecosystem doesn't support 3.1 broadly yet. I'm personally interested to see if 3.1 becomes prevalent before 4.0 is released. Maybe the ecosystem will just skip 3.1?

We generate OAS because it's useful for many folks, including for us in Azure. But like you we didn't have very good luck getting high quality codegen from OpenAPI. Our latest client codegen tech doesn't use OpenAPI, we generate code directly from the TypeSpec, which offers a number of advantages that result in higher quality. Probably at topic for a blog of its own! Anyway, you might be happy to know that we are working on bringing our emitters into the TypeSpec project so anyone can use it with their TypeSpecs.

Re: Write OpenAPI with TypeSpec

#56

Post by FourOnTheFloor »

bterlson wrote: post #55
FourOnTheFloor wrote: post #54

Targeting OpenAPI 3.0 is a bad idea. It wasn't until 3.1 that it became truly useful, if only because it fixed one glaring blunder: Pre-3.1, you inexplicably couldn't provide a description along with a $ref. This defeats one of the major purposes of OpenAPI, which is... documenting your API. Example: If you define a structure called Rectangle and use it all over the place, you can't say what this rectangle means or t…

For what it's worth, we support 3.0 because as you note the ecosystem doesn't support 3.1 broadly yet. I'm personally interested to see if 3.1 becomes prevalent before 4.0 is released. Maybe the ecosystem will just skip 3.1? We generate OAS because it's useful for many folks, including for us in Azure. But like you we didn't have very good luck getting high quality codegen from OpenAPI. Our latest client codegen tech…

Cool, thanks for the reply!

Re: Write OpenAPI with TypeSpec

#57

Post by bterlson »

FourOnTheFloor wrote: post #54

Targeting OpenAPI 3.0 is a bad idea. It wasn't until 3.1 that it became truly useful, if only because it fixed one glaring blunder: Pre-3.1, you inexplicably couldn't provide a description along with a $ref. This defeats one of the major purposes of OpenAPI, which is... documenting your API. Example: If you define a structure called Rectangle and use it all over the place, you can't say what this rectangle means or t…

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...

Re: Write OpenAPI with TypeSpec

#58

Post by Petermarcu »

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.

Wondering if you can generate your service stubs and your clients to use for testing from TypeSpec, could it be faster even in the prototyping/early stages to define your spec first? A la gRpc?

Re: Write OpenAPI with TypeSpec

#60

Post by FourOnTheFloor »

bterlson wrote: post #57
FourOnTheFloor wrote: post #54

Targeting OpenAPI 3.0 is a bad idea. It wasn't until 3.1 that it became truly useful, if only because it fixed one glaring blunder: Pre-3.1, you inexplicably couldn't provide a description along with a $ref. This defeats one of the major purposes of OpenAPI, which is... documenting your API. Example: If you define a structure called Rectangle and use it all over the place, you can't say what this rectangle means or t…

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.

Post reply on HN