Integrate Open API (Swagger) With Node And Express

This article will explain how to integrate swagger (Open API) with Node & express. Swagger makes it very easy for a backend developer to document, test, and explain API endpoints he/she's been working on a front-end developer or anyone looking to consume those endpoints.
 
Integrate Open API (Swagger) With Node And Express
 

Setup 

 
Before we get started into this we should have few things installed in our machine.
Source Code - Git Code
 
Required Packages
 
npm init
npm install swagger-jsdoc swagger-ui-express express nodemon
 
Express - For Server
 
Swagger - For API's Documentation in UI
 
Nodemon - will use this to restart our server automatically whenever we make changes to our files.
 
After installing the required packages let's add the new file to set up the Swagger configuration and as well adding the API endpoints in Node
 
Structure of the Project
 
Integrate Open API (Swagger) With Node And Express
 

Setting up the swagger 

 
Swagger UI can be set up for both the front end & backend as well. Since this article is about the Swagger with Node.js. I will be setting up the the swagger in Node.js express app only. you can explore the other options here
 
In your api.js
  1. //Swagger Configuration  
  2. const swaggerOptions = {  
  3.     swaggerDefinition: {  
  4.         info: {  
  5.             title:'Employee API',  
  6.             version:'1.0.0'  
  7.         }  
  8.     },  
  9.     apis:['api.js'],  
  10. }  
  11. const swaggerDocs = swaggerJSDoc(swaggerOptions);  
  12. app.use('/api-docs',swaggerUI.serve,swaggerUI.setup(swaggerDocs));  
  13.    
After integrating the swagger setup lets define the swagger endpoint with description and response codes in a particular format so that we can able to access those API's inside the swagger after running in the browser 
 
Add Swagger Before Each End Point
  1. /** 
  2.  * @swagger 
  3.  * /Employees: 
  4.  *   get: 
  5.  *     description: Get all Employee 
  6.  *     responses:  
  7.  *       200: 
  8.  *         description: Success  
  9.  *   
  10.  */  
  11. app.get('/Employees',(req,res)=>{  
  12.     res.send([  
  13.         {  
  14.             id:1, Name:'Jk'  
  15.         },  
  16.         {  
  17.             id:2,Name:'Jay'  
  18.         }  
  19.     ])  
  20. });  
For the demo purpose, I have added four API's (Get, Post, Put, Delete) added the swagger setup for the remaining endpoints as well
 
Final api.js
  1. const express = require('express');  
  2. const swaggerJSDoc = require('swagger-jsdoc');  
  3. const swaggerUI = require('swagger-ui-express');  
  4.   
  5. const app = express();  
  6.   
  7. app.listen(5000,()=>console.log("listening on 5000"));  
  8.   
  9. //Swagger Configuration  
  10. const swaggerOptions = {  
  11.     swaggerDefinition: {  
  12.         info: {  
  13.             title:'Employee API',  
  14.             version:'1.0.0'  
  15.         }  
  16.     },  
  17.     apis:['api.js'],  
  18. }  
  19. const swaggerDocs = swaggerJSDoc(swaggerOptions);  
  20. app.use('/api-docs',swaggerUI.serve,swaggerUI.setup(swaggerDocs));  
  21.    
  22. /** 
  23.  * @swagger 
  24.  * /Employees: 
  25.  *   get: 
  26.  *     description: Get all Employee 
  27.  *     responses:  
  28.  *       200: 
  29.  *         description: Success  
  30.  *   
  31.  */  
  32. app.get('/Employees',(req,res)=>{  
  33.     res.send([  
  34.         {  
  35.             id:1, Name:'Jk'  
  36.         },  
  37.         {  
  38.             id:2,Name:'Jay'  
  39.         }  
  40.     ])  
  41. });  
  42.   
  43. /** 
  44.  * @swagger 
  45.  * /Employees: 
  46.  *   post: 
  47.  *     description: Create an Employee 
  48.  *     parameters: 
  49.  *     - name: EmployeeName 
  50.  *       description: Create an new employee 
  51.  *       in: formData 
  52.  *       required: true 
  53.  *       type: String 
  54.  *     responses:  
  55.  *       201: 
  56.  *         description: Created  
  57.  *   
  58.  */  
  59.  app.post('/Employees',(req,res)=>{  
  60.    res.status(201).send();  
  61. });  
  62. /** 
  63.  * @swagger 
  64.  * /Employees: 
  65.  *   put: 
  66.  *     description: Create an Employee 
  67.  *     parameters: 
  68.  *     - name: EmployeeName 
  69.  *       description: Create an new employee 
  70.  *       in: formData 
  71.  *       required: true 
  72.  *       type: String 
  73.  *     responses:  
  74.  *       201: 
  75.  *         description: Created  
  76.  *   
  77.  */  
  78.  app.put('/Employees',(req,res)=>{  
  79.     res.status(201).send();  
  80.  });  
  81.  /** 
  82.  * @swagger 
  83.  * /Employees: 
  84.  *   delete: 
  85.  *     description: Create an Employee 
  86.  *     parameters: 
  87.  *     - name: EmployeeName 
  88.  *       description: Create an new employee 
  89.  *       in: formData 
  90.  *       required: true 
  91.  *       type: String 
  92.  *     responses:  
  93.  *       201: 
  94.  *         description: Created  
  95.  *   
  96.  */  
  97.   app.delete('/Employees',(req,res)=>{  
  98.     res.status(201).send();  
  99.  });  
Run the URL in the browser
 
Now you can do the npm start in the terminal to your app and it will navigate to the browser we have to add the /api-docs at the end of the URL so that i will navigate to the swagger which we have configured and you will see the Swagger UI based on your generated swagger.json.
 
Terminal
 
Integrate Open API (Swagger) With Node And Express
 
Swagger
 
Integrate Open API (Swagger) With Node And Express
 
Testing the API with Swagger
 
Integrate Open API (Swagger) With Node And Express
 
Hope this article helps you !! 
 
Keep learning ......!


Similar Articles