search

swagger-api / swagger-ui

Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.
https://swagger.io
Apache License 2.0
26.38k stars 8.92k forks source link

UI Scalability best practices? #362

Closed aroach closed 9 years ago

aroach commented 10 years ago

Hi there,

I'm wondering if there are any best practices for dealing with API sets that contain a lot (say, 100+ APIs / methods)? It would seem like having a left-hand table of contents type navigation would be useful. Is this something that folks have just generated within their own projects, and split up the resource files to group the API sets?

Thanks!

Ashley

fehguy commented 10 years ago

I saw a very nice customization on top of swagger UI here:

https://www.callfire.com/api-documentation/rest/version/1.1

rage-shadowman commented 10 years ago

Ooohhh... I like that a lot... Would really be nice to have that left hand panel in the default swagger page.

Just a collapsible summary in the left panel that opens up the corresponding operation in the right panel (and collapses all others).

fehguy commented 10 years ago

Yea, I agree. There is one other example that I'd love to get contributions from:

http://api.groupdocs.com/v2.0/spec/#!/system/SetSubscriptionPlan_PUT

Note how the groupdocs guys expand input objects into friendly forms.

rage-shadowman commented 10 years ago

Yeah, that can be nice, but you already have a "click here for template" option that fills in an object template (which in my mind is just as good, or would be if it didn't surround number objects in double quotes).