Stag provides a JavaScript API and a command line tool for generating static documentation from Swagger API metadata.
See the issues for more info, and leave a comment or file an issue if you have suggestions.
First, install stag via npm:
npm install -g stag
Next, write a simple template:
<!DOCTYPE html>
<title>{{ info.title }}</title>
<h1>{{ info.title }} / version {{ apiVersion }}</h1>
Then, point it at a Swagger API URL and your template:
stag http://petstore.swagger.wordnik.com/api/api-docs/ template.html
This will produce:
<!DOCTYPE html>
<title>Swagger Sample App</title>
<h1>Swagger Sample App / version 1.0.0</h1>
Check out the examples for more usage tips, or just run stag --help
:
Swagger static generator version 0.1.0:
stag [ options ] <url> [ <template> [ <output> ] ]
<url> is a Swagger-compliant JSON URL, e.g.
http://petstore.swagger.wordnik.com/api/api-docs
<template> is either:
1. a relative filename,
2. a template name in one of the template paths indicated by one or more -p
or --path options, or
3. empty, "-" or "/dev/stdin" to read the template from stdin
<output> is an optional filename to which the rendered template should be
written, or a directory to which multiple files should be written if
--dir is specified. If left off, the output will be written to stdout.
Examples:
Use only positional arguments:
$ swagger-static $API_URL template.html output.html
Produce output on stdout and redirect to a file:
$ swagger-static $API_URL template.html > output.html
Provide the template on stdin, output on stdout:
$ echo "{{ swaggerVersion }}" | swagger-static $API_URL
Options:
-d, --dir process <template> as a directory of files
-p, --path add this directory to the list of template paths
-a, --autoescape auto-escape HTML in template tags
-E, --enhanced indicates that the Swagger JSON is already 'enhanced'
-e, --encoding when reading the template from stdin, use this encoding
(default: 'utf8')
-v print the version number and exit
Stag uses Nunjucks to render templates, which supports a subset of the template language originally developed for Django and adopted by Jinja, Liquid, [Swig] Plate, and many other template systems. There are some caveats, though.
At 18F we're building Swagger-compliant APIs to make them more accessible and facilitate simpler, dynamically generated documentation for API users. Unfortunately, the only generally accepted way of exposing human-readable Swagger API documentation is SwaggerUI, a client-side JavaScript library with some non-trivial shortcomings:
- 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 was (and is) to make a suite of tools and templates that faciliate the generation of static, human-readable documentation to replace SwaggerUI. Check out the issues to see where I am and provide feedback.