DEV Community

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

Posted on

57 1

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

4. Run Your Server

Start your server:

node index.js

Enter fullscreen mode Exit fullscreen mode

5. 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

Dynatrace image

Observability should elevate – not hinder – the developer experience.

Is your troubleshooting toolset diminishing code output? With Dynatrace, developers stay in flow while debugging – reducing downtime and getting back to building faster.

Explore Observability for Developers

Top comments (0)

Tiger Data image

🐯 🚀 Timescale is now TigerData: Building the Modern PostgreSQL for the Analytical and Agentic Era

We’ve quietly evolved from a time-series database into the modern PostgreSQL for today’s and tomorrow’s computing, built for performance, scale, and the agentic future.

So we’re changing our name: from Timescale to TigerData. Not to change who we are, but to reflect who we’ve become. TigerData is bold, fast, and built to power the next era of software.

Read more

👋 Kindness is contagious

Discover fresh viewpoints in this insightful post, supported by our vibrant DEV Community. Every developer’s experience matters—add your thoughts and help us grow together.

A simple “thank you” can uplift the author and spark new discussions—leave yours below!

On DEV, knowledge-sharing connects us and drives innovation. Found this useful? A quick note of appreciation makes a real impact.

Okay