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

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.