3 ms·

I hope it's better than Swagger 2. I really need something like it, but trying to use Swagger -- after seeing that Kubernetes was using it -- has been a disappo

I hope it's better than Swagger 2. I really need something like it, but trying to use Swagger -- after seeing that Kubernetes was using it -- has been a disappointing experience. 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.

k_sh 10y ago
I assume you've tried Swagger-UI[1] already? We just put out a new version (complete rewrite), you can see it in action here[2]. 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 https://github.com/swagger-api/swagger-ui [2] http://petstore.swagger.io/ http://petstore.swagger.io/
- lobster_johnson 10y ago
  Yes, I'm familiar with it. And I'm sorry to say that I don't like it at all. 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://stripe.com/docs/api/curl https://www.twilio.com/docs/api/rest/sending-messages https://www.twilio.com/docs/api/rest/sending-messages https://plaid.com/docs/api/ https://plaid.com/docs/api/ 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. [1] https://stripe.com/docs/api/curl https://stripe.com/docs/api/curl [2] http://i.imgur.com/x5g1s2R.png http://i.imgur.com/x5g1s2R.png
cshenton 10y ago
I'd suggest RAML for pure documentation. Its way of structuring resources is nested with the URI, so UI generators can use that information to group together in the docs. 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.
- lobster_johnson 10y ago
  Are there any UI generators for it that are worth mentioning, with the sentiments in my other comment [1] in mind? [1] https://news.ycombinator.com/item?id=13927657 https://news.ycombinator.com/item?id=13927657
mhw 10y ago
ReDoc looks pretty good - https://github.com/Rebilly/ReDoc https://github.com/Rebilly/ReDoc I particularly like its approach to presenting hierarchical data structures.
- lobster_johnson 10y ago
  Looks promising, thanks. I think he could use a graphical designer to tighten it up, because it's pretty evident that it's made by a developer. The UX could do some work; needing to click to navigate into data structures on the page is pretty awkward, even if the effect is "cool".

k_sh 10y ago

I assume you've tried Swagger-UI[1] already? We just put out a new version (complete rewrite), you can see it in action here[2]. 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 https://github.com/swagger-api/swagger-ui [2] http://petstore.swagger.io/ http://petstore.swagger.io/

lobster_johnson 10y ago
Yes, I'm familiar with it. And I'm sorry to say that I don't like it at all. 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://stripe.com/docs/api/curl https://www.twilio.com/docs/api/rest/sending-messages https://www.twilio.com/docs/api/rest/sending-messages https://plaid.com/docs/api/ https://plaid.com/docs/api/ 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. [1] https://stripe.com/docs/api/curl https://stripe.com/docs/api/curl [2] http://i.imgur.com/x5g1s2R.png http://i.imgur.com/x5g1s2R.png

cshenton 10y ago

I'd suggest RAML for pure documentation. Its way of structuring resources is nested with the URI, so UI generators can use that information to group together in the docs. 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.

lobster_johnson 10y ago
Are there any UI generators for it that are worth mentioning, with the sentiments in my other comment [1] in mind? [1] https://news.ycombinator.com/item?id=13927657 https://news.ycombinator.com/item?id=13927657

mhw 10y ago

ReDoc looks pretty good - https://github.com/Rebilly/ReDoc https://github.com/Rebilly/ReDoc I particularly like its approach to presenting hierarchical data structures.

lobster_johnson 10y ago
Looks promising, thanks. I think he could use a graphical designer to tighten it up, because it's pretty evident that it's made by a developer. The UX could do some work; needing to click to navigate into data structures on the page is pretty awkward, even if the effect is "cool".