static-api-docs

> Transfrom API documentation stored in [Swagger spec](https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schema) YAML into formatted markdown and static HTML files. See the example output below.


Keywords
gruntplugin
License
Apache-2.0
Install
npm install static-api-docs@0.1.8

Documentation

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  GET    Products



#### /products  ![GET](images/get.png)

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.