Adding Swagger to Your Node.js REST API: A Detailed, Step-by-Step Guide! 🚀

Swagger is a powerful tool for documenting and testing your Node.js REST API. It provides a clear, structured way to define your API endpoints, methods, request and response formats, and much more. In this tutorial, we will guide you step by step on how to add Swagger to your Node.js REST API.

Step 1: Install Swagger UI Express and Swagger Jsdoc

First, we need to install two npm packages: swagger-ui-express and swagger-jsdoc. Run the following command in your terminal:

$ npm install swagger-ui-express swagger-jsdoc

Step 2: Create a Swagger Definition File

Next, create a new file called swaggerDef.js in the root of your project. This file will contain the basic configuration settings for Swagger. Add the following code to your swaggerDef.js file:

const swaggerJsdoc = require('swagger-jsdoc');

const options = {
  swaggerDefinition: {
    openapi: '3.0.0',
    info: {
      title: 'Your API Name',
      version: '1.0.0',
      description: 'A description of your API',
    },
    servers: ['http://localhost:3000'],
  },
  apis: ['./routes/*.js'],
};

const specs = swaggerJsdoc(options);

module.exports = specs;

In this code snippet, we’re defining basic information about your API like the title, version, description, and server. We’re also referencing the routes folder where we’ll define our API endpoints.

Step 3: Initialize Swagger in Your Node.js App

Now, in your Node.js app entry file (e.g. app.js or server.js), add the following code to initialize Swagger:

const express = require('express');
const swaggerUi = require('swagger-ui-express');
const specs = require('./swaggerDef');

const app = express();

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

In this code snippet, we’re creating an Express app, setting up the Swagger UI endpoint using swagger-ui-express, and passing our Swagger definition file to it.

Step 4: Document Your API Endpoints

Now, let’s define your REST API endpoints and document them using Swagger. Create a new file called users.js in a routes folder and add the following code:

/**
 * @swagger
 * /users:
 *   get:
 *     summary: Get all users
 *     description: Retrieve a list of all users
 *     responses:
 *       '200':
 *         description: A list of users
 */
const express = require('express');
const router = express.Router();

router.get('/users', (req, res) => {
  res.json([{ id: 1, name: 'John' }, { id: 2, name: 'Jane' }]);
});

module.exports = router;

In this code snippet, we’re using Swagger annotations to document our GET /users endpoint with a summary, description, and response format.

Step 5: Run Your Node.js App and View Swagger UI

Finally, run your Node.js app using the following command:

$ node app.js

Navigate to http://localhost:3000/api-docs in your browser to view the Swagger UI documentation for your API. You should see a nice, interactive UI that allows you to explore your API endpoints, make test requests, and view response examples.

Congratulations! You have successfully added Swagger to your Node.js REST API. Now you have a comprehensive, easy-to-use documentation for your API that can be shared with your team or consumers. Happy coding!