This document is largely superceded by the swagger-static repo, where I'm now planning a project. GitHub won't notify me of comments here, so if you want to get in touch please comment on or file an issue. Thanks!
At 18F we're implementing Swagger-compliant APIs to make them more accessible and facilitate simpler documentation. Unfortunately, the only generally accepted way of exposing human-readable Swagger API documentation is SwaggerUI, a client-side JavaScript library with some serious issues:
- Because all SwaggerUI-based documentation is rendered at runtime, search engines are [theoretically] unable to crawl their contents.
- Tight coupling with jQuery and a long list of dependencies means that you've got to include everything they include, or it just won't run.
- Tight coupling between the distributed JavaScript source and HTML, e.g. lots of hard-coded CSS selectors means that it's a huge pain to customize the output.
- Unweildy and largely redundant stylesheets, which are tricky to override and impractical to rewrite.
My plan is to make a suite of tools and templates that faciliate the generation of static, human-readable documentation to replace SwaggerUI. At this point, I've made two repos:
- swagger-template, just some HTML files that should theoretically be useful for generating static HTML documentation for a Swagger-compliant API.
- swagger-enhance, a little Node utility for grabbing a Swagger API's JSON and "enhancing" it with JSON data from each of its own endpoints (confusingly, "apis", in Swagger parlance).
The missing piece is a tool I'm referring to as swagger-static
, which would take a swagger-enhance
d JSON representation of an API's metadata and a Django-style template to produce static docs in whatever form you want: primarily HTML, but Markdown might also be useful for Jekyll sites.
Here's how I'm imagining that this could work, using the Discovery API as an example:
swagger-enhance --pretty \
"https://discovery.18f.us/docs/api-docs/api/" > discovery.json
swagger-static \
--template path/to/swagger-template/index.html \
discovery.json > discovery.html
Ideally, swagger-static
would bring the swagger-template
templates with it (e.g., as an npm dependency), then allow you to selectively override one or all of them. Then it would work out of the box without the --template
flag.
I haven't thought through styling the HTML yet, but here are some options:
-
Just bundle a stylesheet with
swagger-template
and let people copy it as needed. -
Make a CDN-hosted default stylesheet and reference that in the
swagger-template
. -
Ignore styling altogether and let
swagger-static
users specify stylesheets in a custom template, e.g.:{% extend "swagger.html" %} {% block css %} <link rel="stylesheet" href="path/to/custom.css"> {% endblock %}
Here are some of my evolution thoughts on this, going beyond just documentation UI - http://apievangelist.com/2014/10/24/someone-please-build-my-open-interactive-portable-and-visual-api-documentation-toolkit/