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

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

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

Что такое OpenAPI и зачем его генерировать?

OpenAPI — это спецификация для описания RESTful API в формате JSON или YAML. Она позволяет:

Автоматически создавать интерактивную документацию (Swagger UI)
Генерировать клиентские SDK для разных языков
Проводить валидацию запросов и ответов
Упрощать интеграцию между командами

Ручное написание спецификации — трудоемкий процесс, который быстро устаревает. Поэтому для Node.js разработаны инструменты, которые генерируют OpenAPI из кода.

Основные инструменты для генерации OpenAPI в Node.js

1. swagger-jsdoc

Самая популярная библиотека, которая парсит JSDoc-комментарии в коде и преобразует их в OpenAPI спецификацию. Устанавливается через npm:

npm install swagger-jsdoc swagger-ui-express

Пример использования с Express:

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

const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: 'Мой API',
      version: '1.0.0',
      description: 'Пример API с генерацией документации'
    },
    servers: [
      { url: 'http://localhost:3000' }
    ]
  },
  apis: ['./routes/*.js'] // путь к файлам с аннотациями
};

const swaggerSpec = swaggerJsdoc(options);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

// Пример маршрута с аннотацией
/**
 * @openapi
 * /users:
 *   get:
 *     summary: Получить список пользователей
 *     tags: [Users]
 *     responses:
 *       200:
 *         description: Успешный ответ
 *         content:
 *           application/json:
 *             schema:
 *               type: array
 *               items:
 *                 $ref: '#/components/schemas/User'
 */
app.get('/users', (req, res) => {
  res.json([{ id: 1, name: 'Иван' }]);
});

app.listen(3000);

2. swagger-autogen

Более современная альтернатива, которая генерирует спецификацию на основе аннотаций в комментариях и автоматически определяет типы данных. Установка:

npm install swagger-autogen

Пример скрипта генерации:

const swaggerAutogen = require('swagger-autogen')();

const doc = {
  info: {
    title: 'Мой API',
    description: 'Описание API'
  },
  host: 'localhost:3000',
  schemes: ['http']
};

const outputFile = './swagger-output.json';
const endpointsFiles = ['./app.js']; // основной файл с маршрутами

swaggerAutogen(outputFile, endpointsFiles, doc).then(() => {
  require('./app.js'); // запуск сервера после генерации
});

В маршрутах достаточно добавить комментарий:

// #swagger.tags = ['Users']
// #swagger.description = 'Эндпоинт для получения пользователей'
app.get('/users', (req, res) => {
  // #swagger.responses[200] = { description: 'Список пользователей' }
  res.json([{ id: 1, name: 'Анна' }]);
});

3. express-oas-generator

Библиотека, которая перехватывает запросы и автоматически строит OpenAPI спецификацию на основе фактических данных. Подходит для прототипов:

npm install express-oas-generator

const express = require('express');
const expressOasGenerator = require('express-oas-generator');
const app = express();

expressOasGenerator.init(app, {}); // инициализация

app.get('/products', (req, res) => {
  res.json([{ id: 1, name: 'Телефон', price: 500 }]);
});

app.listen(3000);

Сравнение инструментов

swagger-jsdoc — зрелая библиотека с большим комьюнити, требует явного описания схем
swagger-autogen — проще в использовании, автоматически определяет типы из кода
express-oas-generator — полностью автоматическая генерация, но менее гибкая