Как задокументировать API с помощью Swagger в Node.js
1. Архитектура сервера
В типичном сервере на Node.js с Express есть несколько основных компонентов:
config – подключение к базе дынных
server.js – основной файл, который запускает сервер
routes/ – папка с маршрутами API
controllers/ – логика обработки запросов
models/ – работа с моделями
swagger.js – генерация документации
swagger_output.json – автоматически созданный JSON-файл со спецификацией
Swagger берет данные из router, формируя на их основе понятное описание API.
2. Установка Swagger
Для работы Swagger в проекте установим два пакета:
npm install swagger-ui-express swagger-autogen
swagger-ui-express – отвечает за отображение документации в браузере
swagger-autogen – автоматически генерирует swagger_output.json из кода
Создадим файл в корне проекта: swagger.js
3. Заполнение swagger.js
const swaggerAutogen = require('swagger-autogen')();
const outputFile = './swagger_output.json'; // Файл, куда сохранится документация const endpointsFiles = ['./routes/*.js']; // Пути к файлам с маршрутами
swaggerAutogen(outputFile, endpointsFiles);
* Когда мы запустим этот файл (node swagger.js), он создаст swagger_output.json.
4. Подключение Swagger в server.js
Теперь добавим Swagger в server.js
const swaggerUi = require('swagger-ui-express');
const swaggerFile = require('../swagger_output.json');
app.use('/doc', swaggerUi.serve, swaggerUi.setup(swaggerFile));
5. Генерация swagger_output.json
Запускаем генерацию Swagger-документации: node swagger.js
После у вас должен сформироваться swagger_output.json в корне проекта
6. Запуск сервера и тестирование
Теперь запустим сервер: node server.js
У меня сервер запущен на порту 3000
Переходим в браузере по адресу: http://localhost:3000/doc
Здесь мы увидим автоматически созданную документацию API, где можно тестировать запросы прямо из браузера, минуя Postman
Swagger не может сам генерировать JSON запросы, как показано на скриншоте в методе POST.
Для этого нужно писать комментарии //#Swagger, либо самому дописывать в swagger_output.json
Но это уже совсем другая история.
Если остались вопросы пишите.