grunt-swagger-spec-generator

Swagger spec generator

Getting Started

This plugin requires Grunt ~0.4.5

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:

1npm install grunt-swagger-spec-generator --save-dev

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

1grunt.loadNpmTasks('grunt-swagger-spec-generator');

The "swagger_spec_generator" task

Overview

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

1grunt.initConfig({
2  swagger_spec_generator: {
3    options: {
4      // Task-specific options go here.
5    },
6    your_target: {
7      // Target-specific file lists and/or options go here.
8    },
9  },
10});

Options

options.dest

Type: String

Default value: 'spec.json'

Target spec file.

options.paths

Type: String / Array

Default value: null

File paths to files containing modules which will be included into paths section of the specification. For example: paths: './test/fixtures/**/*Path.js'

options.definitions

Type: String / Array

Default value: null

File paths to files containing modules which will be included into definitions section of the specification. For example: `definitions: './test/fixtures/**/*Def.js'

options.override

Type: Object

Default value: null

Any overrides which will be applied after importing sections from file. For example:

override: {
    "host": "petstore.swagger.wordnik.com"
}

Available sections to override:

• info
• host
• basePath
• schemes
• paths
• consumes
• produces
• definitions

options.space

Type: Int Default value: 2

Space for pretty format of generated file.

options.validate

Type: Boolean Default value: true

Should validate specs against schema after generating it.

Usage Examples

Models are stored in files which ends with Def. Paths / operations are stored in files which ends with Path.

PetDef.js

1module.exports = {
2    "Pet": {
3        "required": [
4            "id",
5            "name"
6        ],
7        "properties": {
8            "id": {
9                "type": "integer",
10                "format": "int64"
11            },
12            "name": {
13                "type": "string"
14            },
15            "tag": {
16                "type": "string"
17            }
18        }
19    }
20}

PetPostPath.js

1module.exports = {
2    "/pets": {
3        "post": {
4            "description": "Creates a new pet in the store.  Duplicates are allowed",
5            "operationId": "addPet",
6            "produces": [
7                "application/json"
8            ],
9            "parameters": [
10                {
11                    "name": "pet",
12                    "in": "body",
13                    "description": "Pet to add to the store",
14                    "required": true,
15                    "schema": {
16                        "$ref": "#/definitions/newPet"
17                    }
18                }
19            ],
20            "responses": {
21                "200": {
22                    "description": "pet response",
23                    "schema": {
24                        "$ref": "#/definitions/pet"
25                    }
26                },
27                "default": {
28                    "description": "unexpected error",
29                    "schema": {
30                        "$ref": "#/definitions/errorModel"
31                    }
32                }
33            }
34        }
35    }
36};

Gruntfile.js

1swagger_spec_generator: {
2    generate_schema: {
3        options: {
4            definitions: './src/models/**/*Def.js',
5            paths: './src/operations/**/*Path.js',
6            dest: './dist/swagger-spec.json'
7
8        }
9    }
10}

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)