[steve_adams_86]

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.