Swagger for Node JS API
Generating a Documentation in Node JS API is quite simple and it has become an essential task for maintaining and scaling up any project. In this tutorial, we will create Swagger documentation for a Node JS API.
Prerequisites
Before we start, we need to make sure we have some prerequisites installed.
- Node.js installed on your local machine
- Express.js installed in your project
Installing Swagger Documentation
We need to add the below libraries in the package.json
swagger-jsdoc
swagger-ui-express
Create Swagger Spec
We need to create the Swagger specification for our API. We can create a new file named `swagger.json` or just specifying in the index.js . In this file, we define the API endpoints and other related information.
const swaggerOptions = {
definition: {
openapi: "3.0.0",
info: {
title: "Some Title",
version: "0.1.0",
description:
"Some Description",
contact: {
name: "Project",
url: "https://domain.com/",
email: "someemail@domain.com",
},
},
servers: [
{
url: "http://localhost:3000",
description: "Only for Developers"
},
{
url : "https://dev.com",
description: "Development Server"
},
{
url : "https://stage.com",
description: "Stage Server"
},
{
url : "https://prod.com",
description: "Production Server"
}
],
},
apis: ["./server/routes/*.js", "./server/routes/api/*.js"],
};
Configure Swagger
After creating the Swagger spec, we need to configure Swagger. We can do this by creating a new file named `swagger.js` or embed the same in server.js itself like below
const specs = swaggerJsdoc(swaggerOptions);
Integrate Swagger with the Node JS API
Final step is integrating the spec in express module to serve the documentation
app.use(
"/api-docs",
swaggerUi.serve,
swaggerUi.setup(specs, { explorer: true })
);
After the successful start of the server, the documentation page can be reached in browser from the http://localhost:3000/api-docs
Last and final step is specifying the API’s for documentation. Documentation will be specified through the openapi annotation like below. For more specification on the configuration was prodived in the below link About Swagger Specification | Documentation | Swagger
Sample Router:
/**
* @openapi
* /api/v1/getname:
* get:
* tags: [Widget]
* security:
* - bearerAuth : []
* description: Get the list of Names
* responses:
* 200:
* description: list of Names
* 500:
* description: Some Server Error
* 401:
* description: UnAuthorized Access. Kindly check Bearer Token
*/
router.get('/getname', modulename.exportfunction);
Restart the server and again goto http://localhost:3000/api-docs to the list of api specified.