Ask HN: How do you write OpenAPI docs?
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.
3 comments
[ 2.1 ms ] story [ 19.4 ms ] thread- 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.
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.