Giter Club home page Giter Club logo

stag's Introduction

stag

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.

Command Line Usage

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                           

Templates

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.

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:

  1. Because all SwaggerUI-based documentation is rendered at runtime, search engines are [theoretically] unable to crawl their contents.
  2. 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.
  3. 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.
  4. 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.

stag's People

Contributors

shawnbot avatar matejc avatar

Watchers

James Cloos avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.