swagger2aglio

1.2.16 • Public • Published

Swagger to Aglio API Documentation

Build Status Coverage Status Code Climate npm version Dependency Status devDependency Status semantic-release

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

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

Package Sidebar

Install

npm i swagger2aglio

Weekly Downloads

70

Version

1.2.16

License

MIT

Last publish

Collaborators

  • psastras