How often are people hand-writing OpenAPI specs? At least in my experience, such specs are generated from some "authoritative" implementation. This looks like it aims to move the contract-y bits into something less verbose than OpenAPI and less tied to a specific implementation.
I did. I cannot recommend this approach - you often gain little for a lot of pain for editing Yaml. Better just use DSL in your backend language and generate the spec.
Generating the spec from your code is only an option if you are deploying a monorepo.
Hand writing OpenAPI is horrible in my experience. Maybe it's particularly bad because we have a lot of small types that are nested into each other and get composed together a lot, but at the end of the day our OpenAPI YAML needs to be about 1.2MB and I just can't see maintaining that by hand in a text editor.
Handwriting OpenAPI for a bunch of REST APIs will destroy both your keyboard and your sanity. Prefer writing good old x86 assembly over OpenAPI specs. The OpenAPI folks designed the most verbose spec language possible. I guess they took inspiration from Cobol.
Isn't OpenAPI specific to REST? The page also mentions protobuf, for example. Being able to generate clients and servers for those things might be useful, although how well it integrates with the client/server technologies will be the hard bit.
No, OpenAPI has nothing to do with REST. (In fact REST API's are an extra pain in the ass to desribe properly in OpenAPI.)
Agreed, OpenAPI is battle tested and has all the tooling I could ever dream of and then some. It doesn't matter who needs to consume it, there's tools for any and every language.
AWS also has it’s own implementation of this with smithy