Swagger/OpenAPI генерация для Node.js (JavaScript): инструменты и примеры

Swagger/OpenAPI генерация для Node.js (JavaScript)

При разработке современных веб-приложений на Node.js одной из ключевых задач является создание понятной и актуальной документации для API. Swagger (OpenAPI) — это стандарт описания RESTful интерфейсов, который позволяет автоматически генерировать интерактивную документацию, тестировать запросы и поддерживать контракты между клиентом и сервером. В этой статье мы разберем, как настроить генерацию Swagger/OpenAPI документации для Node.js приложений с использованием популярных библиотек.

Что такое Swagger и OpenAPI?

OpenAPI Specification (ранее известный как Swagger Specification) — это формальный стандарт описания HTTP API. Он позволяет:

• Определять эндпоинты, методы, параметры и типы ответов.
• Автоматически генерировать клиентские SDK.
• Создавать интерактивную документацию (Swagger UI).
• Валидировать запросы и ответы.

Для Node.js существует несколько библиотек, упрощающих интеграцию OpenAPI. Рассмотрим две самые популярные: swagger-jsdoc и swagger-ui-express.

Библиотеки для генерации Swagger в Node.js

Основные инструменты:

• swagger-jsdoc — парсит JSDoc-комментарии в коде и собирает из них OpenAPI спецификацию.
• swagger-ui-express — отображает сгенерированную спецификацию в виде интерактивной веб-страницы.
• @nestjs/swagger (если используете NestJS) — декораторы для автоматической генерации.

Мы сосредоточимся на связке swagger-jsdoc + swagger-ui-express для Express.js.

Установка и настройка

Установите необходимые пакеты через npm:

npm install swagger-jsdoc swagger-ui-express

Создайте файл swagger.js с базовой конфигурацией:

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: 'Пример API с автоматической генерацией Swagger',
        },
        servers: [
            { url: 'http://localhost:3000' },
        ],
    },
    apis: ['./routes/*.js'], // путь к файлам с эндпоинтами
};

const swaggerSpec = swaggerJsdoc(options);

module.exports = { swaggerUi, swaggerSpec };

Добавление JSDoc-комментариев к эндпоинтам

Теперь в ваших файлах маршрутов (например, routes/users.js) добавьте комментарии в формате OpenAPI:

/**
 * @openapi
 * /users:
 *   get:
 *     summary: Получить список пользователей
 *     tags: [Users]
 *     parameters:
 *       - in: query
 *         name: limit
 *         schema:
 *           type: integer
 *         description: Количество пользователей (по умолчанию 10)
 *     responses:
 *       200:
 *         description: Список пользователей
 *         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);
});

Аналогично определите модель данных:

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

Подключение Swagger UI к Express

В главном файле приложения (app.js или index.js) добавьте:

const express = require('express');
const { swaggerUi, swaggerSpec } = require('./swagger');

const app = express();

// Маршрут для Swagger UI
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

// Ваши остальные маршруты
app.use('/api', require('./routes/users'));

app.listen(3000, () => {
    console.log('Сервер запущен на http://localhost:3000');
    console.log('Swagger UI: http://localhost:3000/api-docs');
});

Теперь, перейдя по адресу http://localhost:3000/api-docs, вы увидите интерактивную документацию, сгенерированную на основе ваших комментариев.

Дополнительные возможности

Библиоте