Comment by dcre
16 hours ago
Wonderful post and I will be taking inspiration from it. Surprised not to see TypeSpec https://typespec.io/ mentioned, which is a TypeScript-like schema language that I like to describe as "what if OpenAPI was good". I'm guessing they considered it and decided building their own would be both simpler and more flexible. The cost of BYO has come down a lot thanks to agents.
Love TypeSpec, agree it makes writing OpenAPI really easy.
But I’ve moved to using https://aep.dev style APIs as much as possible (sometimes written with TypeSpec), because the consistency allows you to use prebaked aepcli or very easily write your own since everything behaves like know “resources” with a consistent pattern.
Also Terraform works out of the box, with no needing to write a provider.
Which parts of Openapi does it fix?
Open api is an exchange format, it quickly become to verbose and repetitive, it is only OK when auto generated and consumed by tooling.
Looking at the first example - it's far less verbose. Although, seems to be suspiciously minimal, so I can't even tell from a single .tsp route definition what response content type to expect (application/json is the default most likely).
I would guess that is defined by the `@route` decorator.
It’s actually human-readable, it has generics, it supports sum and product types in a much more natural way. There’s a lot more, that’s just off the top of my head.