DEV Community

Gaurang Parante
Gaurang Parante

Posted on • Updated on

How to Integrate Swagger API Documentation into Your Node.js Project

Swagger (now OpenAPI) is a popular tool for designing and documenting RESTful APIs. It provides an interactive and user-friendly way to describe your API's endpoints, request parameters, and responses. In this guide, we'll walk through the process of integrating Swagger API documentation into your Node.js project using swagger-jsdoc and swagger-ui-express.

Step-by-Step Integration
1) Install the Required Packages
First, you need to install the necessary packages. Open your terminal and run the following commands:

npm i swagger-jsdoc
npm i swagger-ui-express

Enter fullscreen mode Exit fullscreen mode

2) Set Up Swagger in Your server.js
Next, import the packages and configure Swagger in your main server file (server.js):

const swaggerJSDoc = require('swagger-jsdoc');
const swaggerUi = require('swagger-ui-express');

Enter fullscreen mode Exit fullscreen mode

Add the following code to set up Swagger:

// Swagger Code
const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'API documentation for project',
      version: '1.0.0'
    },
    servers: [
      {
        url: 'http://localhost:3333/'
      }
    ]
  },
  apis: ['./server.js']
}

const swaggerSpec = swaggerJSDoc(options);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

Enter fullscreen mode Exit fullscreen mode

This code defines the Swagger specification and serves the documentation at the /api-docs endpoint.

3) Document Your API Endpoints
Now, you can add Swagger comments directly in your server.js file to document your API endpoints.

For a GET API:

/**
 * @swagger
 *  /api/users:
 *      get:
 *          summary: Get all users
 *          description: Retrieve a list of all users
 *          responses:
 *              200:
 *                  description: Successfully retrieved list of users
 *                  content:
 *                      application/json:
 *                          schema:
 *                              type: array
 *                              items:
 *                                  type: object
 *                                  properties:
 *                                      id:
 *                                          type: integer
 *                                          description: The user ID
 *                                      name:
 *                                          type: string
 *                                          description: The user's name
 */

Enter fullscreen mode Exit fullscreen mode

For a POST API:

/**
 * @swagger
 *  /route-name:
 *      post:
 *          summary: This is a POST API for action auth
 *          description: For authentication purposes
 *          requestBody:
 *              required: true
 *              content:
 *                  application/json:
 *                      schema:
 *                          type: object
 *                          properties:
 *                              phone_no:
 *                                  type: string
 *                                  description: The user's phone number
 *                              password:
 *                                  type: string
 *                                  description: The user's password
 *                              form_action:
 *                                  type: string
 *                                  description: Form action
 *                          required:
 *                              - phone_no
 *                              - password
 *          responses:
 *              200:
 *                  description: This API is used to fetch data from the database
 *                  content:
 *                      application/json:
 *                          schema:
 *                              type: object
 *                              properties:
 *                                  status:
 *                                      type: boolean
 *                                  message:
 *                                      type: string
 *                                  data:
 *                                      type: object
 */

Enter fullscreen mode Exit fullscreen mode

Replace /route-name with your actual route.

Conclusion
Integrating Swagger API documentation into your Node.js project helps streamline API development and improves collaboration. By following these steps, you can easily set up interactive documentation and ensure your API is well-documented and easy to use.

If you have any questions or need further assistance, feel free to reach out!

Top comments (1)

Collapse
 
dhaval_upadhyay_30f8292a8 profile image
Dhaval Upadhyay

useful and indeed documentation