Swagger — набор инструментов для проектирования, документирования и тестирования REST API по спецификации OpenAPI. Самый известный из них — Swagger UI, интерактивная страница документации, где запрос к API можно отправить прямо из браузера.
Главное отличие — стандарт. Описание API в формате OpenAPI понимают сотни инструментов: от Postman до генераторов кода и порталов документации, поэтому одна спецификация закрывает сразу несколько задач.
Возможности
- Swagger Editor: редактор спецификации OpenAPI в YAML или JSON с проверкой ошибок.
- Swagger UI: интерактивная документация с кнопкой «Try it out».
- Swagger Codegen: генерация клиентских SDK и заготовок сервера.
- SwaggerHub: облачная платформа для командной работы над API.
- Интеграции с фреймворками, которые генерируют спецификацию из кода.
Кому подходит
Бэкенд-разработчикам, которые публикуют API, фронтенд-разработчикам и тестировщикам, которые с ним работают, и командам, где API проектируют до написания кода.
Как начать
Откройте онлайн-редактор Swagger Editor, опишите первый эндпоинт в YAML и посмотрите, как он выглядит в документации. Затем подключите Swagger UI к своему проекту.
Совет
Генерируйте спецификацию из кода с помощью библиотек фреймворка, а не пишите вручную: так документация не будет отставать от реального API.
Ограничения
Оформление Swagger UI выглядит технично. Для красивой публичной документации чаще выбирают Mintlify или ReadMe, а для ручного тестирования запросов — Postman или Insomnia.