static-api-docs

Transfrom API documentation stored in Swagger spec YAML into formatted markdown and static HTML files. See the example output below.

Getting Started

This plugin requires Grunt.

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install static-api-docs --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('static-api-docs');

The "static_api_docs" task

Overview

In your project's Gruntfile, add a section named static_api_docs to the data object passed into grunt.initConfig().

grunt.initConfig({
  static_api_docs: {
   your_target: {
      src: "path/to/the/swagger/spec/YAML/for/API"
      dest: "path/to/the/destination/directory"
      options: {
		filename: "filename"
		suppressMD: false
		suppressHTML: false
	  }
    },
  },
})

Options

target.options.filename

Type: String Default value: 'api-doc'

A string value that will be the root of the generated files (api-doc.md, api-doc.html).

target.options.suppressMD

Type: Boolean Default value: false

A boolean that turns off generation of markdown output.

target.options.suppressHTML

Type: Boolean Default value: false

A boolean that turns off generation of HTML output.

Usage Examples

grunt.initConfig({
  static_api_docs: {
    test: {
      src: 'swagger.json',
      dest: 'outputDir',
      options: {
        filename: 'my-static-doc',
      }
    }
  },
})

Example Input and Output

Some example output created by this plugin and some example JSON following Swagger spec .

Uber API: v1.0.0

Table of Contents

/products      Products

---

#### /products  

Get all products with all attributes.

Parameters

Name	Required	In	Type	Description
category	false	query	string	Filter by product category (e.g., "gizmo")

Success 200 (Object[])

Name	Type	Description
product_id	string	Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles.
description	string	Description of product.
display_name	string	Display name of product.
category	string	Category of product. For example, "gizmo".

Error 500 (Object)

Name	Type	Description
code	integer
message	string
fields	string

---

Notes on nested response JSON

In the event that your response JSON includes nested data, Static API Docs will render the nested properties with indentation. For example, a response property named "components" might be an object array, and can be represented ins Swagger spec JSON like:

"components": {
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "component_id": {
        "type": "integer",
        "description": "Unique identifier."
      },
      "component_name": {
        "type": "string",
        "description": "Display name of component."
      }
    }
  }
}

The plugin will render the object array like this:

Name	Type	Description
components	Object[]
- component_id	integer	Unique identifier representing a specific component of a product.
- component_name	string	Display name of component.

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

(Nothing yet)

License

Copyright (c) 2015 Spatial Development International, LLC. Licensed under the Apache license.