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.
First, install stag via npm:
npm install -g stag
Next, 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.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
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:
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.
FAQs
Generate Swagger documentation, statically
We found that stag demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.