Integrate Swagger in your NodeJS Application

Posted By : S. Ajit | 27-Feb-2017

nodejs

In simple word swagger has provide API description and also provide a way to hit backend API like postman. Follow below written steps to implement swagger in nodejs Application.

STEP 1: First step is to generate swagger specification for which we are going to use swagger-jsdoc. install swagger-jsdoc via npm:

 npm install swagger-jsdoc  --save

STEP 2: Require swagger-jsdoc in your app.js file.

var swaggerJSDoc = require('swagger-jsdoc');

STEP 3: Add below written lines to your app.js

// swagger definition
var swaggerDefinition = {
  info: {
    title: 'Node Swagger API',
    version: '1.0.0',
    description: 'Hello i am swagger . I am one step ahead of postman. My job is to provide API description',
  },
  host: 'localhost:3000',
  basePath: '/',
};

// options for swagger jsdoc 
var options = {
  swaggerDefinition: swaggerDefinition, // swagger definition
  apis: ['./configurations/UrlMapping.js'], // path where API specification are written
};

// initialize swaggerJSDoc
var swaggerSpec = swaggerJSDoc(options);

STEP 4: Create a route for swagger.json file . This json file will have all description about APIs. Add below written lines to app.js

// route for swagger.json
app.get('/swagger.json', function(req, res) {
  res.setHeader('Content-Type', 'application/json');
  res.send(swaggerSpec);
});

If you hit route http://localhost:3000/swagger.json you will be able to see json like this

{
  info: {
    title: "Node Swagger API",
    version: "1.0.0",
    description: "xx"
  },
  host: "localhost:3000",
  basePath: "/",
  swagger: "2.0",
  paths: { },
  definitions: { },
  responses: { },
  parameters: { },
  securityDefinitions: { }
}

STEP 5: Now in your URL mapping file add comments above API in YAML format like this:

        /**
         * @swagger
         * /user:
         *   post:
         *     tags:
         *       - User
         *     description: Save user
         *     produces:
         *       - application/json
         *     parameters:
         *       - name: user
         *         description: User object
         *         in: body
         *         required: true
         *         schema:
         *           $ref: '#/definitions/User'
         *     responses:
         *       200:
         *         description: Return saved user
         *         schema:
         *           $ref: '#/definitions/User'
         */

Above is for a POST request in which we are sending data in body also you can see that there is schema in comments.

schema: #ref: '#/definitions/User'

It is a swagger definition for schema which will be like this and is written on the top of URL mapping

    /**
     * @swagger
     * definition:
     *   User:
     *     properties:
     *       firstName:
     *         type: string
     *       lastName:
     *         type: string
     *       email:
     *         type: string
     *       password:
     *         type: string
     *       role:
     *         type: string
     */

Here are the few example of swagger specification.

GET:

        /**
         * @swagger
         * /user/{id}:
         *   get:
         *     tags:
         *       - User
         *     description: Get specific user
         *     produces:
         *       - application/json
	 *     parameters:
	 *       - name: id
	 *         description: User id
	 *         in: path
	 *         required: true
	 *         type: string
         *     responses:
         *       200:
         *         description: Get user by id
         */

POST:

        /**
         * @swagger
         * /user:
         *   post:
         *     tags:
         *       - User
         *     description: Save user
         *     produces:
         *       - application/json
         *     parameters:
         *       - name: user
         *         description: User object
         *         in: body
         *         required: true
         *         schema:
         *           $ref: '#/definitions/User'
         *     responses:
         *       200:
         *         description: Return saved user
         *         schema:
         *           $ref: '#/definitions/User'
         */

PUT:

            /**
             * @swagger
             * /user/{id}:
             *   put:
             *     tags:
             *       - User
             *     description: Update specific user detail
             *     produces:
             *       - application/json
	     *     parameters:
	     *       - name: id
             *         description: User id
	     *         in: path
	     *         required: true
	     *         type: string
	     *       - name: user object
	     *         description: user data
	     *         in: body
	     *         required: true
	     *         schema:
             *           $ref: '#/definitions/UpdateUserObj'
             *     responses:
             *       200:
             *         description: Update user
             */

DELETE:

            /**
             * @swagger
             * /user/{id}:
             *   delete:
             *     tags:
             *       - User
             *     description: Delete specific user detail
             *     produces:
             *       - application/json
	     *     parameters:
	     *       - name: id
	     *         description: User id
	     *         in: path
	     *         required: true
	     *         type: string
             *     responses:
             *       200:
             *         description: Delete user
             */

STEP 6: Now download Swagger UI from github and add to swagger UI folder to your application directory where static files are placed. Rename Swagger UI folder to swagger-doc

STEP 7: Replace url = "http://petstore.swagger.io/v2/swagger.json"; to url = "http://localhost:3000/swagger.json"; in index.html which is in dist folder of swagger-UI

STEP 8: Now hit this route http://localhost:3000/swagger-doc/dist , You will be able to see your APIs as shown in screen shot below