[Fannon]

OpenApi 3.0 is quite nice to work with. Its verbose to write by hand, though and you also need to know JSONSchema. With the Swagger UI we've had some mixed experiences. Not everything you can express in the Spec is displayed very well. But for developers, it's a nice playground / entrypoint for backend projects. We wouldn't want to miss that. (You also get this for GraphQL with the GraphQL Playground)

One of the most important features of an API Doc is that it tells the complete truth and is always up to date. An OpenApi Spec therefore really "wants" to be auto-generated. There we've had mixed experiences, aswell. If the generator is not working as expected or missing a feature important to you, you're either limited or you take on generating it yourself.

I've used an approach a while ago, I was quite happy with, but it took some effort: Everything API related has one definitite source of truth. Out of that, generate the docs, example and specs you need. Also use this for validation. For Documentation, I've used a wiki. The generated docs or code snippets were generated as Templates, and could be embedded/transcluded in the documentation, which was otherwise hand-written. This provided a nice mix of written and generated content with full flexibility.