Implement Swagger API Documentation in Node.js (2025 Guide)

Building APIs without documentation is like shipping code without comments — it works, but it's painful to maintain. That's where Swagger (OpenAPI 3.0) comes in. It helps you create beautiful, interactive API documentation directly from your Node.js code.

In this guide, you'll learn how to integrate Swagger with an Express.js project — step by step.

What Is Swagger (OpenAPI)?

Swagger (now known as OpenAPI Specification) is a comprehensive toolset for describing, producing, and consuming RESTful APIs. It provides a standardized way to document and interact with APIs.

Swagger enables developers to:

Step 1 — Initialize Your Node.js Project

Create a new directory and initialize your Node.js project:

1mkdir node-swagger-api && cd node-swagger-api
2npm init -y
3npm install express swagger-ui-express swagger-jsdoc

Step 2 — Create Basic Express Server

Create a basic Express server in server.js:

1const express = require('express');
2const app = express();
3app.use(express.json());
4 
5app.get('/api/v1/hello', (req, res) => {
6  res.json({ message: 'Hello Swagger!' });
7});
8 
9app.listen(3000, () => console.log('Server running on http://localhost:3000'));

Step 3 — Configure Swagger Documentation

Create swagger.js file to configure your API documentation:

1const swaggerJsdoc = require('swagger-jsdoc');
2const swaggerUi = require('swagger-ui-express');
3 
4const options = {
5  definition: {
6    openapi: '3.0.0',
7    info: {
8      title: 'Node.js API Docs',
9      version: '1.0.0',
10      description: 'API documentation using Swagger in Node.js',
11    },
12    servers: [
13      {
14        url: 'http://localhost:3000',
15      },

Step 4 — Integrate Swagger with Express

Add Swagger UI middleware to your Express server in server.js:

1const { swaggerUi, swaggerSpec } = require('./swagger');
2app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

Visit http://localhost:3000/api-docs to view your interactive API documentation.

Step 5 — Document an Example Route

Create a routes/ folder and add a user.js file with Swagger annotations:

1/**
2 * @swagger
3 * /api/v1/user:
4 *   get:
5 *     summary: Get user info
6 *     responses:
7 *       200:
8 *         description: Success
9 */
10app.get('/api/v1/user', (req, res) => {
11  res.json({ id: 1, name: 'John Doe' });
12});

Final Thoughts

With minimal setup, you now have a live API documentation portal that your entire team can use for testing, learning, and integration.

Key Benefits

Use this in production with proper security (e.g., API key auth) and serve docs only in development.