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

#javascript #programming #productivity #webdev

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

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');

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));

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
 */

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
 */

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!