I'm particularly frustrated with the lack of good documentation generators. That's more important, in my opinion, than using it to generate clients and servers.
If you're not a fan, please feel free to open a ticket to give us some feedback.
Disclosure: I was contracted to build Swagger-Editor 3.0.
[1] https://github.com/swagger-api/swagger-ui [2] http://petstore.swagger.io/
Some things I dislike:
* It's just a flat list of endpoints. You have to click on each to get a description, and it has this sluggish animation that opens up. I want to browse.
* Way too much wasted screen real estate. The huge, wide table that shows when an endpoint is "open" is ridiculous.
* For any given type, have to switch between "Example Value" and "Model", which is awkward. There's a missed opportunity there, too: Consider the "PUT /user/{username}". Why is the "type" of the body not User? Why couldn't it be a link to the model? I.e. "PUT" takes a User and returns a User. Swagger-UI uses so much empty space to represent this very simple protocol.
* Whatever is being used to display the model is hard to use and read. You have to click on the little arrow to expand each level, and the font sizes are very inconsistent.
etc.
I do wish I had something vastly superior to give as an example, but I can find a lot of faults with every single API documentation site out there that I can think of. I do know some decent ones, though:
https://stripe.com/docs/api/curl
https://www.twilio.com/docs/api/rest/sending-messages
This is the level of quality you at least have to reach before my interest is piqued.
I like that these include runnable client examples in multiple languages, and includes more than just dry reference documentation; there are descriptions of actual semantics. Moreover, the documentation is presented in an organized way, by topic, and let's the user consume the information linearly without lots of clicks.
As a simpler example, years ago a colleague of mine made a simple autogenerated documentation browser with built-in request running (screenshot [2]), which turned out pretty good. It's simple, but still miles ahead of Swagger-UI in terms of usability. I sometimes wish I'd spent some effort working it into something reusable.
I particularly like its approach to presenting hierarchical data structures.
Also it supports union types for request/resp. Which means that you can template a URI and have multiple response schemas to go with different values of the template. Unlike swagger which forces you to enumerate every endpoint if you want them to have different response schemas, which is very ugly for logically grouped sets of resources which aren't explicitly part of a collection.