DEV Community

Cover image for Swagger + Node.js (Express) : A Step-by-Step Guide
cuongnp
cuongnp

Posted on

Swagger + Node.js (Express) : A Step-by-Step Guide

Following the post on configuring Swagger for a SpringBoot project, today I will introduce you to a step-by-step guide to set up Swagger in a Node.js (Express) project.

1. Set Up Your Project

First, create a new Node.js project if you don't have one already.



mkdir swagger-demo
cd swagger-demo
npm init -y
npm install express swagger-ui-express swagger-jsdoc



Enter fullscreen mode Exit fullscreen mode

2. Create Your Express Server

Create an index.js file (or app.js, depending on your preference):



touch index.js


Enter fullscreen mode Exit fullscreen mode


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

const app = express();
const port = process.env.PORT || 3000;

// Swagger setup
const swaggerOptions = {
  swaggerDefinition: {
    myapi: '3.0.0',
    info: {
      title: 'My API',
      version: '1.0.0',
      description: 'API documentation',
    },
    servers: [
      {
        url: 'http://localhost:3000',
      },
    ],
  },
  apis: ['./routes/*.js'], // files containing annotations as above
};

const swaggerDocs = swaggerJsDoc(swaggerOptions);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));

// Sample route
app.get('/api/hello', (req, res) => {
  res.send('Hello World!');
});

app.listen(port, () => {
  console.log(`Server is running on http://localhost:${port}`);
});



Enter fullscreen mode Exit fullscreen mode

3. Document Your Routes

Create a routes folder and add a hello.js file to it (or any route file):



mkdir routes
cd routes
touch hello.js


Enter fullscreen mode Exit fullscreen mode

Then, add the following code to hello.js:



/**

  • @swagger
  • /api/user:
  • get:
  • summary: Retrieve a list of users
  • responses:
  • 200:
  • description: A list of users
  • content:
  • application/json:
  • schema:
  • type: array
  • items:
  • type: object
  • properties:
  • id:
  • type: integer
  • example: 1
  • name:
  • type: string
  • example: John Doe */ app.get('/api/user', (req, res) => { res.json([{ id: 1, name: 'John Doe' }]); });
Enter fullscreen mode Exit fullscreen mode



  1. Run Your Server

Start your server:



node index.js

Enter fullscreen mode Exit fullscreen mode



  1. Access Swagger UI

Open your browser and navigate to http://localhost:3000/api-docs. You should see the Swagger UI with your documented API.

Swagger-javascript

Following these steps, you can configure Swagger for your JavaScript project, providing interactive API documentation for your development team and end-users.

Thank you for reading! See you in the next post.

Swagger + SpringBoot Project

Top comments (0)