The way I see it, there are at least two ways of doing this: via codegen/programmatically or writing it manually. Which side are you on?<p>If you use codegen or similar, what tool do you use? For example there is `swaggo` in Go language, utoipa in Rust, Fastify (JavaScript) can has built-in way to write schema IIRC.<p>If you write the JSON/YAML manually, how do you write it? Honestly, I want to write it manually but the lack of IDE autocomplete makes it very hard.<p>Or is there any other way to write it, lemme know.
Depends rather on the project.<p>So, in my current role (Go) I generate part of the code for new APIs that I am implementing, <i>from</i> OpenAPI specs. I just write those JSON specs manually in my IDE - The JetBrains tools (not sure if it's a plugin?) have a real-time preview you can have up side by side, which is good enough, with the openapi standard open on the other monitor.<p>While in an old role we had a legacy (Java) system which was a bit of a pain for others to integrate with, so we did the reverse - With a little bit of work we had an endpoint serving up a Swagger UI with autogenerated API docs (based on our comments/annotations) for people to read, for all those old existing APIs.
- Break OpenAPI files into different files and use swagger-cli to combine them.<p>- Generate server/client for go using oapi-codegen and for Typescript using OpenAPI.<p>The tooling on the IDE side certainly lacks a bit but you don't miss it much.<p>I have yet to evaluate <a href="https://typespec.io/" rel="nofollow">https://typespec.io/</a> if that fits the purpose.