Swagger — инструментарий описания REST API¶
Swagger — это набор инструментов (toolkit) для описания, документирования и проектирования RESTful API, построенный на основе одноимённой спецификации формата описания API. Первоначально создан в 2011 году Райаном Бруком (Ryan Brook) и Тони Тамом (Tony Tam) для внутренних нужд компании Wordnik; с 2015 года развивается под эгидой OpenAPI Initiative и переименован в OpenAPI Specification, тогда как термин «Swagger» закрепился за инструментарием (Swagger UI, Swagger Codegen, Swagger Editor), работающим поверх этой спецификации.
¶История
Проект Swagger был запущен в 2011 году стартапом Wordnik, занимавшимся словарём и API для работы с ним. Формат описания позволял декларативно описать конечные точки, методы, схемы данных и аутентификацию REST-сервиса. В 2014 году SmartBear Software, компания, занимавшаяся инструментами качества ПО, выкупила права на Swagger и передала спецификацию в Linux Foundation. В 2015 году была основана OpenAPI Initiative, в которую вошли Google, Microsoft, IBM, PayPal, Capital One и другие компании; результатом стало переименование спецификации в OpenAPI Specification (OAS). Версии 2.0 (2014), 3.0 (2017) и 3.1 (2021) стали основными вехами развития формата. Термин «Swagger» сохранился за инструментарием и продолжает широко использоваться в разговорной речи как синоним OpenAPI.
¶Спецификация OpenAPI
Спецификация описывает API в формате JSON или YAML. Структура документа включает:
- openapi — версия спецификации;
- info — метаданные: название, версия, описание;
- paths — перечень конечных точек и поддерживаемых HTTP-методов (GET, POST, PUT, DELETE и др.);
- components/schemas — схемы данных в синтаксисе JSON Schema, описывающие структуру запросов и ответов;
- servers — адреса серверов, на которых развернуто API;
- security — схемы аутентификации (API-ключи, OAuth 2.0, HTTP Basic и другие);
- tags — логическая группировка операций.
Пример минимального описания конечной точки в YAML:
``yaml paths: /pets: get: summary: Список питомцев responses: '200': description: Успешный ответ ``
¶Инструменты Swagger
¶Swagger UI
Веб-интерфейс, автоматически генерирующий интерактивную документацию из OpenAPI-документа. Позволяет просматривать описания операций, схемы данных и выполнять запросы к API прямо из браузера (функция «Try it out»). Интегрируется в приложения на Django, Spring Boot, Express, ASP.NET Core и других платформах.
¶Swagger Editor
Браузерный редактор с подсветкой синтаксиса YAML/JSON, встроенной валидацией по спецификации и предпросмотром документации. Доступен как веб-приложение и как локальная установка.
¶Swagger Codegen
Генератор клиентских SDK и серверных заглушек (stubs) на 40+ языках и фреймворках (Java, Python, JavaScript, Go, C#, Ruby и др.) из OpenAPI-документа. Позволяет автоматизировать создание клиентской части интеграции.
¶Swagger Hub
Облачная платформа для совместной работы над API-документацией, управления версиями и публикации спецификаций.
¶Применение
Swagger/OpenAPI применяется в нескольких сценариях:
- Документирование — автоматическая генерация читаемой интерактивной документации вместо ведения отдельного wiki.
- Проектирование (design-first) — спецификация выступает контрактом между командами фронтенда и бэкенда, согласуемым до начала разработки.
- Тестирование — из спецификации генерируются автотесты, проверяющие соответствие реализации описанию.
- Валидация — в рантайме схемы используются для проверки корректности входящих запросов и исходящих ответов.
- Генерация кода — клиентские библиотеки и серверные заглушки создаются автоматически, что сокращает рутинную работу.
В российской практике OpenAPI-описания используются при разработке внутренних корпоративных API и в проектах цифровых платформ; инструменты Swagger входят в стандартные стеки популярных Java-фреймворков (Springfox, springdoc-openapi).
¶Swagger и OpenAPI: различия
Терминологическая путаница возникла после передачи спецификации OpenAPI Initiative. Строго говоря, спецификация — это OpenAPI Specification, а Swagger — название инструментов, её реализующих. На практике «Swagger» часто используется как обобщённое имя формата, особенно в разговорной речи и старых проектах.
¶Критика
К основным ограничениям спецификации относят:
- сложность описания сложных сценариев взаимодействия (цепочек запросов, WebSocket, Server-Sent Events) — в OAS 3.1 поддержка WebSocket по-прежнему отсутствует на уровне спецификации;
- разрастание документа при описании больших API, что затрудняет поддержку;
- расхождения между спецификацией и фактической реализацией API, возникающие при ручном ведении описания.
¶См. также
- REST
- JSON Schema
- gRPC
- API网关
¶Источники
- OpenAPI Specification — официальная документация (openapis.org)
- Swagger Docs — документация инструментов (swagger.io)
- Fowler M. «Contract Testing» / martinfowler.com
- Amundsen M. «RESTful Web APIs», O'Reilly, 2013