swagger-jsdoc-generator

    1.0.3 • Public • Published

    swagger-jsdoc-generator

    npm version Build Status XO code style

    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.

    License

    Licensed under MIT License. © Luciano Mammino.

    Install

    npm i swagger-jsdoc-generator

    DownloadsWeekly Downloads

    800

    Version

    1.0.3

    License

    MIT

    Last publish

    Collaborators

    • lmammino