Skip to content

twskj/pretty-swag

Repository files navigation

pretty-swag

pretty-swag is a UI for Swagger Specification V2. It is inspired by Swagger Editor.

An example of the generated html from petstore spec can be found here

Bugs filing and suggestions are always welcome.

Changelog

See CHANGELOG

Requirement

Node js

Installation

npm install pretty-swag -g

Usage

pretty-swag -i input.json
pretty-swag -c config.json
pretty-swag -i input.json -o output.html
pretty-swag -i input.json -o output.html -f lite
pretty-swag -i input.json -o output.html -f offline -m true
pretty-swag -i input.json -o output.html -f offline -m true -th default

API Usage

Syntax prettySwag.run(input,output,config,callback);

API Example

const prettySwag = require('pretty-swag');

config = {};
config.format = "singleFile";
config.markdown = true;
config.fixedNav = true;
config.autoTags = true;
config.theme = {
    "default": "blue",
    "GET": "blue",
    "POST": "indigo",
    "DELETE": "red",
    "PUT": "amber"
};

input = "input.json";
output = "doc.html";

prettySwag.run(input,output,config,function(err){
    if(err){
        console.log(err);
    }
    else{
        console.log("success");
    }
});

When dst equals null, no file will be written and the html will be returned as second parameter.

...
prettySwag.run(input,null,config,function(err,data){
    if(err){
        console.log(err);
    }
    else{
        console.log(data); // Plain html
    }
});

Command switch

Switch Name Optional Description
-i input No Location of a Swagger spec file(can be JSON or YAML)
-o output Yes Location of generated document(s). Default to doc.html
-f format Yes Format of the output (singlefile, offline, lite, noicon). Default to singlefile
-m markdown Yes Render Summary & Description as markdown. true or false. Default to false
-th theme Yes One of the supported colors or pre-defined theme default
-c config Yes Location of a configuration file
-fixedNav fixedNav Yes Include this flag to fixed the navigation bar on screen
-autoTags autoTags Yes Include this flag to turn on/off automatically generate tags by path and method name
-noDate noDate Yes Include this flag to remove generated date
-noCredit noCredit Yes Include this flag to remove credit
-noNav noNav Yes Include this flag to remove navigation bar. Default to false
-noReq noRequest Yes Include this flag to remove request panel. Default to false
-noBaseURL noBaseURL Yes Include this flag to suppress baseURL. Default to false
-indent indent Yes Include this flag to specify space per indentation. Default to 3
-v version Yes To show pertty-swag current version
-collapsePath collapse.path Yes Collapse path by default. true or false. Default to false
-collapseMethod collapse.method Yes Collapse method by default. true or false. Default to false
-collapseTool collapse.tool Yes Collapse tool by default. true or false. Default to true
-home.url home.url Yes A home URL. Leave it blank to suppress the display
-home.location home.location Yes A location on navigation bar. Either L (Left) RL (Right before Expand) RR(Right most)
-home.text home.text Yes A text on navigation bar. Default to Home

Configuration File

Valid keys are:

  • input
  • output
  • format
  • markdown
  • theme
  • fixedNav
  • hideNav
  • autoTags
  • noDate
  • noCredit
  • noRequest
  • indent
  • collapse
  • customCSS
  • home

Example of Configuration file

{
  "input": "/tmp/petstore.json",
  "output": "/tmp/petstore.html",
  "format": "singlefile",
  "markdown": true,
  "theme": {
    "default": "blue",
    "GET": "blue",
    "POST": "indigo",
    "DELETE": "red",
    "PUT": "amber"
  },
  "fixedNav": true,
  "autoTags": true,
  "indent": 2,
  "collapse":{
    "path":true
    ,"method":true
    ,"tool":true
  }
  "home":{
      "URL": "https://github.com/twskj/pretty-swag/"
      ,"location": "RR"
      ,"text": "Home"
  }
}

Available Colors

  • red
  • pink
  • purple
  • deep-purple
  • indigo
  • blue
  • light-blue
  • cyan
  • teal
  • green
  • light-green
  • lime
  • yellow
  • amber
  • orange
  • deep-orange
  • brown
  • grey
  • blue-grey
  • black
  • white

Output format

  • SingleFile - A single html embedded all fonts and icon in one file. (Default).
  • Offline - A html file and a resource folder for css and js.
  • Lite - A single html but need the internet connection to obtain required resources.
  • NoIcon - Does not use Roboto font, and no icons (Useful when dealing with older IEs)

Features

  • Search / Filter by Tag

  • Collapsible Panel

  • Fold / Unfold Schema

  • Live Request / Response Feedback

  • Syntax Highlight code block

  • Download and Preview response data

Filtering

  • Use prefix - to exclude unwanted tags. For example -store will exclude api(s) that contain store tag.

Console

  • Press Ctrl + ` to bring up a console
  • Press tab to auto complete

Available Console Commands

Command Description
add header -g <key> <value> Adding the header to all paths/methods
remove header -g <key> <value> Remove a given header from all paths/methods

License

The contents of this repository are covered under the MIT License

Support on Beerpay

Like the project? buy me some 🍻!

Beerpay Beerpay