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