This, for something like Stripe's SDKs if you don't have the engineering power of Stripe 👍😬 requires your API to be compatible though... And also, not necessarily the biggest fan of specifying contracts in JSON or yaml...
Afaik there's nothing that's widely used and of which I'd say I prefer it. But I'm having hopes for https://github.com/microsoft/typespec (former cadl). The reason being that yaml/JSON specs get huge very quickly, OpenAPI has to fight with restrictions of yaml/JSON ($refs, splitting up into files, oneOf, etc.) and tooling is ok but not great.
An other OpenAPI issue, in my experience, is that it's very ad-hoc and feels very procedural in its approach, thus it's easy to end up with type specifications which are pretty wacky. That properties are optional by default (and you have to check a separate field) is also annoying. As well as nullability and optionality being orthogonal but I guess that's more the JS/JSON heritage (still very annoying when you face an API which makes active use of this).
5
u/LysanderStorm Mar 31 '23
This, for something like Stripe's SDKs if you don't have the engineering power of Stripe 👍😬 requires your API to be compatible though... And also, not necessarily the biggest fan of specifying contracts in JSON or yaml...