shawnbot/swagger-static.md

## swagger-static.md

      
    Raw
  

              swagger-static.md
            
          
    swagger-static

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!
Background

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.

The Plan

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-enhanced 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 %}