stag
v0.1.0
Published
Generate Swagger documentation, statically
Downloads
4
Readme
stag
The stag Node module provides a JavaScript API and a command line tool for generating static documentation from Swagger API metadata.
See the issues for more info, and comment on one or file an issue if you have suggestions.
Command Line Usage
First, install stag via npm:
npm install -g stagNext, write a simple Django-style 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.htmlThis 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 Background
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.