swagger-jsdoc-generator

Command line script that generates a swagger file based on jsdoc comments.

Usage

You can use the command as follows

swagger-jsdoc-generator config.js

Where config.js is the path to the configuration file.

If you don’t specify a configuration file the command will look by default for swaggerJsdoc.config.js in the current working directory.

This will print in the standard output a swagger definition in JSON format, so you can easily pipe the output to another command or to a file.

E.g.:

swagger-jsdoc-generator config.js | mySwaggerDoc.json

or, assuming you have some utility to convert the definition to HTML, you could do

swaggerToHtml < swagger-jsdoc-generator config.js

More detailed example on how to configure and use the command later here.

Requirements

This package requires Node.js (version >= 4.0.0) and NPM (version >= 2.14.2).

Install

Global install:

npm install --global swagger-jsdoc-generator

As dev dependency (e.g. if needed as part of a build process):

npm install --save-dev swagger-jsdoc-generator

Configuration

The configuration file is used to specify which files needs to be scanned to look for jsdoc swagger documentation and other options.

A configuration file can be a plain JSON file or a javascript module exporting an object.

An example of configuration is the following:

{
  "swaggerDefinition": {
    "info": {
      "title": "My api",
      "version": "1.0.0",
    },
  },
  "apis": ["src/myApi.js"]
}

All the options supported by swagger-jsdoc (which is the module used internally by the command) are supported.

You can also check out an example of dynamic configuration through node modules.

Example

Here’s a brief example about how to document an API:

// src/mySampleApi.js

/**
 * @swagger
 * /login:
 *   post:
 *     description: Login to the application
 *     produces:
 *       - application/json
 *     parameters:
 *       - name: username
 *         description: Username to use for login.
 *         in: formData
 *         required: true
 *         type: string
 *       - name: password
 *         description: User's password.
 *         in: formData
 *         required: true
 *         type: string
 *     responses:
 *       200:
 *         description: login
 */
app.post('/login', function(req, res) {
  res.json(req.body);
});

Then you need to have mySampleApi.js in your conf.json configuration file:

{
  "swaggerDefinition": {
    "info": {
      "title": "My sample api",
      "version": "1.0.0"
    }
  },
  "apis": ["src/mySampleApi.js"]
}

Finally you can run the command to produce the swagger definition:

swagger-jsdoc-generator conf.json

which will produce the following output:

{
  "info": {
    "title": "My sample api",
    "version": "1.0.0"
  },
  "swagger": "2.0",
  "paths": {
    "/login": {
      "post": {
        "description": "Login to the application",
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "username",
            "description": "Username to use for login.",
            "in": "formData",
            "required": true,
            "type": "string"
          },
          {
            "name": "password",
            "description": "User's password.",
            "in": "formData",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "200": {
            "description": "login"
          }
        }
      }
    }
  },
  "definitions": {},
  "responses": {},
  "parameters": {},
  "securityDefinitions": {},
  "tags": []
}

Contributing

Everyone is very welcome to contribute to this project. You can contribute just by submitting bugs or suggesting improvements by opening an issue on GitHub.