Забыли, как устроен собственный API? С VPS и Swagger это больше не проблема. В статье показываем, как быстро сгенерировать интерактивную документацию, протестировать все запросы прямо в браузере и поддерживать актуальность API даже при изменениях на бэкенде. Всё наглядно, удобно и без лишних телодвижений — особенно полезно, если разворачиваете сервисы на VPS и работаете в команде.
Введение
Документация API — то, что делает ваш сервис понятным для разработчиков и для вас самих через полгода. Но писать её вручную бывает скучно, сложно и долго. К счастью, есть Swagger — набор инструментов, превращающий описание API в живую, интерактивную страницу.
Поговорим о том, как настроить Swagger для документирования и тестирования API. Объяснили, что такое Swagger и OpenAPI, как подключить нужные инструменты, описали эндпоинты и протестировали API прямо в браузере.
Аренда VPS/VDS — от ₽219/месяц
Почему выбирают VPS от AdminVPS:
✓ Дешевле физического сервера
✓ Более гибкий и мощный, чем обычный хостинг
✓ Бесплатная защита от DDoS и техподдержка 24/7
✓ Масштабируется под любые задачи
Виртуальный сервер VPS/VDS — ваш личный сервер для сайтов, магазинов, ботов и других проектов.
Что такое Swagger и OpenAPI
Swagger — это экосистема инструментов для документирования, тестирования и проектирования REST API. В её основе лежит спецификация OpenAPI — формализованный язык описания API, позволяющий точно задать структуру всех методов, параметров, ответов и ошибок. Благодаря ему и разработчики, и машины могут «понимать» API без лишних пояснений.
Как работает Swagger
Ключевое преимущество Swagger — возможность превратить техническое описание API в интерактивную документацию, которую можно открыть в браузере. Вместо бесконечных JSON-файлов и устаревающих wiki-страниц вы получаете наглядный интерфейс с разбивкой по методам, схемами запросов и примерами ответов.
Swagger UI — это визуальный интерфейс, где можно:
- посмотреть структуру всех эндпоинтов и их параметры;
- протестировать запросы прямо на лету (без Postman и curl);
- увидеть, что именно вернёт сервер при разных входных данных;
- быстро найти нужный метод благодаря группировке и поиску.
Такой подход особенно ценен, если у вас десятки или сотни методов — документация остаётся актуальной автоматически, без ручного обновления.
Swagger и командная работа
Swagger можно внедрять ещё на этапе проектирования. Пока бэкенд только создаётся, фронтенд-команда, мобильные разработчики и QA уже работают с контрактом API — то есть с описанием, на которое все ориентируются. Это снижает количество ошибок и недопониманий при интеграции: каждый знает, как работает тот или иной метод, какие данные ждать и в каком формате их передавать.
Если вы разворачиваете проект на VPS, подключение Swagger поможет быстрее наладить взаимодействие между микросервисами, а также обеспечит прозрачность для новых участников команды или заказчиков.
Инструменты Swagger для документирования и тестирования API
| Компонент | Назначение |
|---|---|
| OpenAPI | Формат описания API в формате YAML/JSON |
| Swagger UI | Веб-интерфейс для чтения и тестирования API |
| Swagger Editor | Онлайн-редактор для написания и валидации OpenAPI-спецификаций |
| Swagger Codegen | Генерация клиентского кода и серверных заглушек по описанию API |
| SwaggerHub | Платформа для командной работы и централизованного хранения документации |
Настройка Swagger: пошаговая инструкция
Предположим, у вас уже есть сервер с работающим REST API на любом языке или фреймворке. Ниже описан универсальный процесс, который мы покажем на примере Node.js + Express. При других технологиях шаги будут похожими по сути.
Шаг 1. Установка Swagger-инструментов в проект
Первым делом нужно подключить Swagger к вашему приложению. Существует два основных подхода:
- Spec-First (через файл спецификации). Вы вручную создаёте файл описания API в формате OpenAPI (YAML или JSON), а затем подключаете Swagger UI, чтобы визуализировать этот файл.
- Code-First (через код). Вы отмечаете ваши маршруты в коде специальными комментариями или аннотациями, либо используете библиотеку, которая автоматически генерирует описание API на основе кода. Swagger потом берёт сгенерированную спецификацию и строит документацию.
Новичкам проще начать с генерации через код. Мы пойдём по этому пути. В случае Node.js есть удобные библиотеки:
- swagger-ui-express — встраивает веб-интерфейс документации в Express-приложение,
- swagger-jsdoc — генерирует спецификацию OpenAPI из комментариев в коде.
Установите их командой:
npm install --save swagger-ui-express swagger-jsdocЭти пакеты открытые и регулярно обновляются. Аналоги есть практически для любой платформы: например, для Python (Flask, Django) существуют расширения Flasgger или drf-yasg, для Java Spring Boot — библиотека springdoc-openapi и так далее. Принцип везде один: добавить зависимость Swagger и настроить её.
Шаг 2. Описание API в формате OpenAPI
Далее нужно создать спецификацию OpenAPI, описывающую API. Если вы используете подход Code-First, как мы, то пишете описание прямо в коде в виде JSDoc-комментариев. Если предпочитаете Spec-First, можно открыть онлайн-редактор Swagger Editor и составить YAML-документ там, как вам удобнее. Рассмотрим вариант с комментариями в коде.
Представьте, у нас есть маршрут в Express для получения списка пользователей:
app.get('/users', (req, res) => {
// ... ваша логика обработки запроса …
res.json([ /* список пользователей */ ]);
});Чтобы задокументировать этот эндпоинт с помощью swagger-jsdoc, достаточно добавить над ним специальный комментарий формата Swagger (JSDoc). Например:
/**
* @openapi
* /users:
* get:
* summary: Получить список всех пользователей
* responses:
* 200:
* description: Список пользователей успешно получен
*/Этот комментарий описывает метод GET на пути /users, краткое описание действия (summary) и возможный ответ с кодом 200. Вы можете расписать и параметры, и тело ответа — спецификация OpenAPI позволяет подробно описать каждый аспект API от параметров запросов до схем данных. При старте приложения библиотека swagger-jsdoc найдёт такие комментарии и сгенерирует на их основе объект спецификации.
Совет
Если пока не хочется писать комментарии, можно сгенерировать черновой вариант документации автоматически. Существует пакет swagger-autogen, который сканирует Express-маршруты и формирует базовый файл swagger.json. Это быстрый способ получить основу спецификации, которую потом можно дополнить вручную.
Важно, чтобы описание API соответствовало формальным правилам OpenAPI. Ошибки синтаксиса приведут к тому, что Swagger UI не сможет показать документацию. Для проверки удобно использовать Swagger Editor (он подсвечивает ошибки) или утилиту командной строки swagger-cli. Например, выполнив команду swagger-cli validate myapi.yaml, вы узнаете, корректен ли ваш YAML-файл. Не пренебрегайте валидацией, особенно если правите спецификацию вручную.
Шаг 3. Интеграция Swagger UI в приложение
Визуальный интерфейс Swagger UI в случае Node.js подключается несколькими строками кода. Добавьте в файл настройки сервера, например, app.js или index.js, следующие строчки:
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerJsdoc = require('swagger-jsdoc');
const app = express();
// Конфигурация swagger-jsdoc: укажите основные сведения и путь к файлам с комментариями
const swaggerSpec = swaggerJsdoc({
definition: {
openapi: '3.0.0',
info: {
title: 'Пример API пользователей',
version: '1.0.0',
description: 'Документация для API управления пользователями',
},
},
apis: ['./routes/*.js'], // пути к файлам, содержащим JSDoc-комментарии
});
// Подключите middleware Swagger UI на маршрут /api-docs
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
// ... остальной код настройки серверных маршрутов и запуск сервера …После этого перезапустите ваше приложение. Документация станет доступна по указанному URL, в примере это /api-docs. Откройте в браузере:
http://localhost:3000/api-docsВы должны увидеть сгенерированную Swagger-страницу с названием вашего API, описанием и списком эндпоинтов. Интерфейс Swagger UI — это одностраничное веб-приложение: справа находятся интерактивные элементы управления, а слева перечислены разделы документации.
Если вы используете другую платформу, шаг интеграции будет отличаться синтаксисом, но схож по сути. Например, в Java достаточно добавить зависимость springdoc-openapi-ui, и Swagger UI автоматически появится по адресу /swagger-ui.html. В PHP есть решения типа swagger-php, в .NET — встроенные средства через Swashbuckle, которые тоже выводят docs на /swagger или /swagger/ui. То есть, где бы ни работал ваш бэкенд, с высокой доли вероятности уже есть готовый плагин для Swagger. И конечно, вы всегда можете скачать Swagger UI как статический HTML/JS/CSS (архив доступен на GitHub) и просто открыть свой YAML-файл в нём.
На этапе развёртывания убедитесь, что документация доступна только тем, кому следует. Если вы выкладываете API в продакшен, можно защитить Swagger UI паролем или закрыть доступ извне, чтобы внутренние детали API были видны только команде. На VPS-сервере от AdminVPS вы легко сможете настроить отдельный адрес для Swagger UI и ограничить к нему доступ.
Шаг 4. Тестирование API через интерфейс документации
Swagger UI хорош не только тем, что наглядно отображает ваши эндпоинты — он позволяет взаимодействовать с ними в реальном времени. Перейдя на страницу документации, вы увидите разделы, соответствующие тегам или контроллерам вашего API, а внутри конкретные методы (GET, POST, и т.д.).
Swagger UI позволяет играться с API прямо на странице документации. Вы можете указать необходимые параметры запроса или тело (для POST/PUT запросов). Затем нажмите Execute. Swagger UI отправит запрос на ваш API и отобразит результат прямо под формой. Вы увидите сгенерированный запрос, например, команду curl с вашим URL и заголовками, и блок Response с ответом сервера: код состояния (200, 404 и т.д.), возвращённые данные в формате JSON/XML и заголовки. Если что-то пойдёт не так, например, сервер вернёт ошибку, вы увидите соответствующее сообщение и код ошибки, что тоже ценно для отладки.
Обратите внимание на кнопку Authorize в виде замочка в Swagger UI. Она служит для ввода общих данных авторизации. Если ваш API требует, скажем, JWT-токен, OAuth2 или API-ключ, вы можете нажать Authorize, ввести там креды, и Swagger UI автоматически будет подставлять их во все дальнейшие запросы. Так можно тестировать даже защищённые методы API, не прописывая вручную заголовки Authorization каждый раз.
Помимо отправки запросов и отображения ответов, Swagger UI позволяет переключаться между серверами, если в спецификации перечислены, например, dev и prod адреса, просматривать модели данных в удобном формате, копировать примеры запросов. Вы сразу видите свой API глазами пользователя и можете убедиться, что эндпоинты работают и описаны правильно.
Шаг 5. Поддержка документации в актуальном состоянии
Документация ценна, пока она отражает реальное состояние API. Поэтому при каждом изменении серверного кода не забывайте обновлять спецификацию.
Если вы пошли по пути генерации из кода, как в нашем примере, то обновления будут подгружаться автоматически: вы добавили новый маршрут с комментариями, перезапустили приложение, и Swagger UI уже показывает новый эндпоинт. В некоторых случаях, например, при использовании swagger-autogen, нужно запустить дополнительный скрипт генерации, чтобы перезаписать файл swagger.json.
Также рекомендуем вынести описание общих компонентов API в раздел components OpenAPI или в отдельный файл, если инструмент позволяет. Это помогает не писать одно и то же по сто раз и использовать общие части в разных местах. Swagger поддерживает рефы ($ref) — вы можете определить схему объекта один раз и ссылаться на неё во всех методах, где этот объект используется.
Помните, что Swagger-документация дополняет, но не заменяет полноценное руководство. Swagger UI покрывает прежде всего справочную часть, такую как эндпоинты, параметры, модели. Если вашему API нужны большие вступления или обучающие разделы, позаботьтесь о них отдельно.
Заключение
Создание документации для API больше не кажется невыполнимой задачей, правда? С помощью Swagger вы настроили автогенерацию удобной интерактивной страницы, где все методы вашего сервиса разложены по полочкам. Больше никаких устаревших таблиц с параметрами — всё обновляется вместе с кодом и доступно для мгновенного тестирования.
Пользуйтесь этим инструментом и дальше: подключайте его в новых проектах, экспериментируйте с возможностями, например, генерируйте клиентские SDK через Swagger Codegen, и продолжайте улучшать качество вашей разработки.
Читайте в блоге:
- Как защитить API с JWT: пошаговое руководство
- В чём разница между API нейросетей и хостингом для ИИ: что выбрать
- Мониторинг производительности с Grafana Tempo: гайд по трассировке приложений
