swagger2aglio

Swagger to Aglio API Documentation

Swagger2Aglio is a REST API documentation generator. It converts a Swagger API description into the API Blueprint format and then to Aglio documentation. The final output is a single static HTML page, easily served from any webserver.

Currently supports Swagger version 2.0.

Example Output

Three column streak theme screenshot:

Example output is generated from the IBM Watson API

• Default two column theme

  swagger2aglio -i petstore_expanded.yml -o examples/default.html

• Streak two column wide theme

  swagger2aglio -i petstore_expanded.yml --theme-full-width -o examples/streak_wide.html

• Slate two column wide theme

  swagger2aglio -i petstore_expanded.yml --theme-full-width -o examples/slate_wide.html

• Flatly three column theme

  swagger2aglio -i petstore_expanded.yml --theme-variables flatly --theme-template triple -o examples/flatly_triple.html

• Slate three column theme

  swagger2aglio -i petstore_expanded.yml --theme-variables slate --theme-template triple -o examples/slate_triple.html

Installation and Usage

There are two ways to use swagger2aglio: as an executable or as a library for Node.js.

Executable

Install swagger2aglio via NPM. You need Node.js installed.

npm install -g swagger2aglio

Then, start generating HTML.

# Default theme
swagger2aglio -i input.yml -o output.html

# Use three-column layout
swagger2aglio -i input.yml --theme-template triple -o output.html

# Built-in color scheme
swagger2aglio --theme-variables slate -i input.yml -o output.html

# Customize a built-in style
swagger2aglio --theme-style default --theme-style ./my-style.less -i input.yml -o output.html

Node.js Library

You can also use swagger2aglio as a library. First, install and save it as a dependency:

npm install --save swagger2aglio

Then, convert some Swagger to HTML:

var swagger2aglio = require('swagger2aglio');
var options = {
  input: './petstore_expanded.yml',
  themeVariables: 'default'
}
swagger2aglio.convert(options, function (err, html) {
    if (err) return console.log(err);

    console.log(html);
});

Reference

swagger2aglio.convert (options, callback)

Render a Swagger file to HTML. Available options are:

Option	Type	Default	Description
input	string		The input Swagger definition file
theme	string	'default'	Theme name to load for rendering
noMinify	boolean	false	If false, does not minify output

In addition, the default theme provides the following options:

Option	Type	Default	Description
themeVariables	string	default	Built-in color scheme or path to LESS or CSS
themeCondenseNav	bool	true	Condense single-action navigation links
themeFullWidth	bool	false	Use the full page width
themeTemplate	string		Layout name or path to custom layout file
themeStyle	string	default	Built-in style name or path to LESS or CSS

Development

For development, first clone the repository. Then install dependencies:

npm install

To start the development hot reload server, run:

npm run start

Then, in a browser go to http://localhost:3000 and select an example. Changes made to any of the Jade templates will be automatically reloaded and displayed in the browser.

License

Copyright (c) 2016 Paul Sastrasinh