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
-
swagger2aglio -i petstore_expanded.yml -o examples/default.html
-
swagger2aglio -i petstore_expanded.yml --theme-full-width -o examples/streak_wide.html
-
swagger2aglio -i petstore_expanded.yml --theme-full-width -o examples/slate_wide.html
-
swagger2aglio -i petstore_expanded.yml --theme-variables flatly --theme-template triple -o examples/flatly_triple.html
-
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 = ;var options = input: './petstore_expanded.yml' themeVariables: 'default'swagger2aglio;
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