I feel like people want swagger to generate good docs for them, so they jam all the auto-gen annotations and what not into their code base and pump out the default generated docs and more or less leave it at that. And it's awful. The code base swells up with annotations and the docs are permanently neglected.

I haven't come across many swagger-based docs that I liked.

Having said that, I agree that it's a problem with the user, not the tool. Swagger is fine, you should just put some effort into using it well.

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.

I used to connect to REST (and SOAP/Graphql I guess, but that's not relevant) APIs for a living. Probably connected to about 200 or so. Swagger styled docs are only as good as the devs who write them. They have the potential to be pretty...but I couldn't care less about that.

Some of the worst docs I've ever seen used swagger. Some of the best I've seen used swagger, so the tool doesn't make the docs IMO.

I'd rather you email me a .txt file that's well organized and complete (including a damned baseURL, you heathens) than pretty swagger docs without substance.

With https://github.com/timothycrosley/hug these docs are autogenerated, which is nice.