Swagger/OpenAPI Generation for Node.js (JavaScript): Tools and Examples

Swagger/OpenAPI Generation for Node.js (JavaScript)

When developing modern web applications in Node.js, one of the key tasks is creating clear and up-to-date API documentation. Swagger (OpenAPI) is a standard for describing RESTful interfaces that allows you to automatically generate interactive documentation, test requests, and maintain contracts between the client and server. In this article, we will walk through how to set up Swagger/OpenAPI documentation generation for Node.js applications using popular libraries.

What are Swagger and OpenAPI?

The OpenAPI Specification (formerly known as the Swagger Specification) is a formal standard for describing HTTP APIs. It allows you to:

• Define endpoints, methods, parameters, and response types.
• Automatically generate client SDKs.
• Create interactive documentation (Swagger UI).
• Validate requests and responses.

For Node.js, there are several libraries that simplify OpenAPI integration. Let's look at the two most popular ones: swagger-jsdoc and swagger-ui-express.

Libraries for Swagger Generation in Node.js

The main tools are:

• swagger-jsdoc — parses JSDoc comments in the code and compiles them into an OpenAPI specification.
• swagger-ui-express — displays the generated specification as an interactive web page.
• @nestjs/swagger (if using NestJS) — decorators for automatic generation.

We will focus on the swagger-jsdoc + swagger-ui-express combination for Express.js.

Installation and Setup

Install the required packages via npm:

npm install swagger-jsdoc swagger-ui-express

Create a swagger.js file with the basic configuration:

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

const options = {    definition: {        openapi: '3.0.0',        info: {            title: 'My Node.js API',            version: '1.0.0',            description: 'Example API with automatic Swagger generation',        },        servers: [            { url: 'http://localhost:3000' },        ],    },    apis: ['./routes/*.js'], // path to files with endpoints};

const swaggerSpec = swaggerJsdoc(options);

module.exports = { swaggerUi, swaggerSpec };

Adding JSDoc Comments to Endpoints

Now, in your route files (e.g., routes/users.js), add comments in OpenAPI format:

/** * @openapi * /users: *   get: *     summary: Get a list of users *     tags: [Users] *     parameters: *       - in: query *         name: limit *         schema: *           type: integer *         description: Number of users (default 10) *     responses: *       200: *         description: List of users *         content: *           application/json: *             schema: *               type: array *               items: *                 $ref: '#/components/schemas/User' */router.get('/users', async (req, res) => {    const users = await getUsers(req.query.limit || 10);    res.json(users);});

Similarly, define the data model:

/** * @openapi * components: *   schemas: *     User: *       type: object *       properties: *         id: *           type: integer *         name: *           type: string *         email: *           type: string */

Connecting Swagger UI to Express

In the main application file (app.js or index.js), add:

const express = require('express');const { swaggerUi,