How do you write OpenAPI docs?

Question

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?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.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.Or is there any other way to write it, lemme know.

ooFieTh6 · Accepted Answer

Depends rather on the project.So, in my current role (Go) I generate part of the code for new APIs that I am implementing, from 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.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.

wg0 · Answer

- Break OpenAPI files into different files and use swagger-cli to combine them.
- Generate server/client for go using oapi-codegen and for Typescript using OpenAPI.
The tooling on the IDE side certainly lacks a bit but you don't miss it much.
I have yet to evaluate https://typespec.io/ if that fits the purpose.

steveklabnik · Answer

Dropshot, the Rust HTTP framework I use, has an option to generate an OpenAPI document for your server. I use that.