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

[bterlson]

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

[FourOnTheFloor]

Hadn't heard of that, thanks.

Does TypeSpec have description fields? I don't think I've seen any in the examples.

[bterlson]

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.

[FourOnTheFloor]

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.

[bterlson]

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

[FourOnTheFloor]

Thanks. Never having seen a description in this language, I wouldn't know that the above syntax designated one; it looks like a comment.

I also can't find any similar strings in any of the samples in the drop-down list.

[bterlson]

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.

[mstade]

Is this client generation available anywhere, or internal tooling?

[bterlson]

We're working on bringing it into the TypeSpec project as we speak. You can see an initial demo of it working in this repo: https://github.com/bterlson/typespec-todo.

[mstade]

Awesome – thank you so much for sharing!

[FourOnTheFloor]

Cool, thanks for the reply!