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.
Setup
Before we get started into this we should have few things installed in our machine.
- Visual Studio Code -> Visual Studio Code
- Node.js -> Node.js
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
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
-
-
const
swaggerOptions = {
-
swaggerDefinition: {
-
info: {
-
title:
‘Employee API’
,
-
version:
‘1.0.0’
-
}
-
},
-
apis:[
‘api.js’
],
-
}
-
const
swaggerDocs = swaggerJSDoc(swaggerOptions);
-
app.use(
‘/api-docs’
,swaggerUI.serve,swaggerUI.setup(swaggerDocs));
-
Add Swagger Before Each End Point
-
-
-
-
-
-
-
-
-
-
-
app.get(
‘/Employees’
,(req,res)=>{
-
res.send([
-
{
-
id:1, Name:
‘Jk’
-
},
-
{
-
id:2,Name:
‘Jay’
-
}
-
])
-
});
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
-
const
express = require(
‘express’
);
-
const
swaggerJSDoc = require(
‘swagger-jsdoc’
);
-
const
swaggerUI = require(
‘swagger-ui-express’
);
-
-
const
app = express();
-
-
app.listen(5000,()=>console.log(
“listening on 5000”
));
-
-
-
const
swaggerOptions = {
-
swaggerDefinition: {
-
info: {
-
title:
‘Employee API’
,
-
version:
‘1.0.0’
-
}
-
},
-
apis:[
‘api.js’
],
-
}
-
const
swaggerDocs = swaggerJSDoc(swaggerOptions);
-
app.use(
‘/api-docs’
,swaggerUI.serve,swaggerUI.setup(swaggerDocs));
-
-
-
-
-
-
-
-
-
-
-
-
app.get(
‘/Employees’
,(req,res)=>{
-
res.send([
-
{
-
id:1, Name:
‘Jk’
-
},
-
{
-
id:2,Name:
‘Jay’
-
}
-
])
-
});
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
app.post(
‘/Employees’
,(req,res)=>{
-
res.status(201).send();
-
});
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
app.put(
‘/Employees’
,(req,res)=>{
-
res.status(201).send();
-
});
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
app.
delete
(
‘/Employees’
,(req,res)=>{
-
res.status(201).send();
-
});
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
Swagger
Testing the API with Swagger
Hope this article helps you !!
Keep learning ……!
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
