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));
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');
  5. const app = express();
  7. app.listen(5000,()=>console.log("listening on 5000"));
  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));
  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. });
  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 ......!