express-swagger-generator

Express Swagger Generator

Installation

npm i express-swagger-generator --save-dev

Usage

const express = require('express');
const app = express();
const expressSwagger = require('express-swagger-generator')(app);

let options = {
    swaggerDefinition: {
        info: {
            description: 'This is a sample server',
            title: 'Swagger',
            version: '1.0.0',
        },
        host: 'localhost:3000',
        basePath: '/v1',
        produces: [
            "application/json",
            "application/xml"
        ],
        schemes: ['http', 'https']
    },
    basedir: __dirname, //app absolute path
    files: ['./routes/**/*.js'] //Path to the API handle folder
};
expressSwagger(options)
app.listen(3000);

Open http://<app_host>:<app_port>/api-docs in your browser to view the documentation.

How to document the API

/**
 * This function comment is parsed by doctrine
 * @route GET /api
 * @group foo - Operations about user
 * @param {string} email.query.required - username or email
 * @param {string} password.query.required - user's password.
 * @returns {object} 200 - An array of user info
 * @returns {Error}  default - Unexpected error
 */
exports.foo = function() {}

For model definitions:

/**
 * @typedef Point
 * @property {integer} x.required
 * @property {integer} y.required
 * @property {string} color
 */

 // Now I can use it as below:

 /**
  * Insert a point
  * @route POST /api/point
  * @param {Point.model} point.body.required - the new point
  */

More

This module is based on express-swaggerize-ui and Doctrine-File