The benefits of using Swagger/OpenAPI are to maintain consistent API specifications, validation and documentation.
And the Swagger UI documentation tool initially looks very attractive cosmetically. However there’s no publishing or privacy restriction features. The reason is that the Swagger API spec itself doesn’t support publishing controls.
That’s fine for Open source authors and most internal-only corporate users, but commercial sites will be unhappy without more control.
So it’s important to decide well before ship date if the Swagger UI will work for you, or if you need to find another solution (ie. you might find it to be “more hole than donut.”)
Swagger UI showing API endpoints (the colored bars) and Auth Dialog. Note the double Authorize buttons. Everything you see is live (auto-generated from the Swagger API spec file.)
Here’s a summary of the Swagger UI issues that I’ve observed when writing a non-trivial API:
|#||Swagger UI Issue||Solution|
|1.||Swagger UI makes your Swagger API spec file downloadable by end-users||A half-step is to use Basic Auth for viewing it, but authenticated end-users can still save it to disk. A plan would be to run it server-side.|
|2.||Swagger UI by default sends your Swagger API spec file to an external validation service||Fixable.
|3.||the “Try it out” buttons” are active, letting anybody too easily send GET, DELETE, PUT, POST, PATCH commands to your server, whether the request makes sense or not||Fixable. See supportedSubmitMethods parameter.|
|4.||the default branding is for the Swagger project||Fixable. Read docs or just use Firefox Inspector on Swagger UI header and change the CSS/JS.|
|5.||the UI tool is nice, but even nicer is professionally written text with detailed examples||Not fixable. Outside the scope of Swagger UI.|
|6.||the UI tool does not publish to a static file. Most commercial publishers want to provide a PDF file.||Not easily fixable, though you can load your Swagger spec file into the Swagger Editor, drag the left frame further left, “print as PDF” and edit the text with Libre Office.|
|7.||No ability to restrict on displaying paths or request methods||Not easily fixable. You could export a minimal Swagger API spec file just for use with Swagger UI.|
|8.||Add username and password auth||Easy. Just add a securitydefinitions block in your Swagger spec file and define the key name in Swagger UI’s index.html. Note that multiple auth methods require showing and clicking multiple “Authorize” buttons (see screenshot above) since the Swagger specification considers multiple auth methods to logically OR and your app has to sort them out.|
|9.||Add API key auth||Easy. Supported by current versions.|
|10.||URL bar shows address of Swagger spec file||Fixable, but end-users can still download your spec file:
|11.||Themes||Some are available at swagger-ui-themes|
|12.||There can be one “body” parameter at most.||The Swagger spec only allows one body element (formData or JSON) while you may want to allow both. Some parsers enforce that, and some don’t.|
|13.||Swagger UI markdown is broken/incomplete.||As of Feb. 2017, markdown support is missing numbered lists, italics, tables and more. Please post a comment when numbered item lists and line continuations work. See Issue #825 for more context.|
* by “not fixable” and “not easily fixable” I mean “total Swagger UI re-design and rewrite required.” 🙂
Getting Started with Swagger UI
- unzip or clone master to a public directory
- update dist/index.html with the location of your api.json file
- if you’re using a load balancer and see an error like “cannot call https from http”, change scheme from https to http in your Swagger API spec file.
Customizing the Swagger UI
How to break swagger 2.0 JSON file into multiple modules
Tom Johnson’s Tutorial
Tuan’s Tip to Add Username and Password (Check spelling carefully)
A Visual Guide to What’s New in Swagger 3.0
Note: if you google or stackoverflow for help, ignore any bug reports about Swagger UI before 2016.
Swagger Editor Custom UI
blog.novatec-gmbh.de: The problems with Swagger, HN discussion
Top 7 Myths about HTTPS and Browser Caching
Ask HN: What’s the best way to write an API spec?
robwin.eu: Documentation of a REST API with Swagger and AsciiDoc
Document your Already Existing APIs with Swagger