Write OpenAPI with TypeSpec

Post by mstade » Sat, Mar 30, 2024, 2:05 AM UTC

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…

Post by FourOnTheFloor » Sun, Mar 31, 2024, 11:28 PM UTC

bterlson wrote: post #70

FourOnTheFloor wrote: post #68

Earlier quoted context omitted.

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 {}