As someone who used openAPI for the first time recently, I don’t understand the benefit.
Im building an integration between two different API’s. I was given the openAPI spec and instructed to find a mock server generator to get a boilerplate app up. I spent like two hours trying to find some sort of generator that provides value. All the generators I tried seemed half baked (I wanted to use rails for this project, because that’s what I am most familiar developing in. I understand rails is a sub optimal choice for this project.)
In the time I wasted trying to find a generator, I could’ve just wrote the code by hand. Once I just started manually writing code, everything started moving much quicker. Even if I had used a generator, I’d still need to manually update things every time the interface changes, yeah? Who is openAPI for?
I have extensively used OpenAPI Specs for years.
You're right that tools are almost all partially-baked.
I use specs to generate data models in TypeScript, Kotlin, and .NET (for different projects). This gives me compile-time guarantees that my API docs match my code.
I also use it for generating documentation and client SDKs in other languages.
If used correctly, it can help automate hundreds or thousands of hours of error-prone work. It also forms an unbreakable contract between systems in totally different languages (not unlike what Protobufs could be used for).
It takes a few hours to find tools you like, but after that, it's generally smooth.
How do you use it for generating documentation? Can you generate anything other than Swagger UI for API docs?
There are tons of hosted solutions for docs (Apimatic, SwaggerHub, Stoplight, and Apicurio Studio).
My favorites are SwaggerHub[2] and Apicurio[3], because their editors are solid and they have good compatibility with all the nooks and crannies of the OpenAPI v3 spec.
1. https://github.com/Redocly/redoc