The benefits of using Swagger are to maintain consistent API specifications, validation and documentation.
And the Swagger UI 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.”)
Image may be NSFW.
Clik here to view.
Swagger UI showing API endpoints (the colored bars) and Auth Dialog. 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 business APIs:
| # | Swagger UI Issue | Solution |
|---|---|---|
| 1. | Swagger UI makes your Swagger API spec file downloadable by end-users | Not fixable. A half-step is to use Basic Auth for viewing it, but authenticated end-users can still save it to disk. |
| 2. | Swagger UI by default sends your Swagger API spec file to an external validation service | Fixable. validatorUrl: null |
| 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: document. |
| 11. | Themes | Some are available at swagger-ui-themes |
* by “not fixable” and “not easily fixable” I mean “total Swagger UI re-design and rewrite required.” Image may be NSFW.
Clik here to view.
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
Test Parameter
Security Tokens
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)
Note: if you google or stackoverflow for help, ignore any bug reports about Swagger UI before 2016.