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:

!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.

$3

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

``shell
npm install -g swagger2aglio
`

Then, start generating HTML.

`shell


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
`

$3

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

`shell
npm install --save swagger2aglio
`

Then, convert some Swagger to HTML:

`js
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:

`shell
npm install
`

To start the development hot reload server, run:

`shell
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