Swagger — спецификация и инструменты для REST API¶
Swagger — это набор открытых спецификаций и инструментов для описания, документирования и проектирования RESTful API. Первоначально создан в 2011 году как формат описания API, позже развился в экосистему, включающую язык описания OpenAPI Specification (OAS), инструменты генерации документации и вспомогательные утилиты для разработчиков. В 2015 году спецификация была передана Фонду OpenAPI Initiative, входящему в состав Linux Foundation, и переименована в OpenAPI Specification, тогда как название Swagger закрепилось за линейкой инструментов компании SmartBear Software.
¶История
Проект Swagger был запущен в 2011 году компанией Reverb Technologies (позже приобретённой SmartBear Software). Первая версия спецификации описывала структуру REST-сервисов в формате JSON и позволяла автоматически генерировать интерактивную документацию. Формат быстро получил распространение благодаря тому, что решал проблему «договорённости» между фронтендом и бэкендом: разработчики могли описать API в одном файле и на его основе строить клиентские библиотеки, тесты и документацию.
В 2014–2015 годах ведущие технологические компании, включая Google, Microsoft, IBM и Apigee, выступили с инициативой создания независимого открытого стандарта для описания API. В сентябре 2015 года инициатива была оформлена как OpenAPI Initiative под эгидой Linux Foundation. Спецификация Swagger 2.0 была преобразована в OpenAPI Specification 2.0, сохранив обратную совместимость. В 2017 году вышла версия OAS 3.0, а в 2021 году — OAS 3.1, полностью совместимая со стандартом JSON Schema.
¶OpenAPI Specification
OpenAPI Specification — это формат описания REST API в виде YAML- или JSON-документа. Он позволяет зафиксировать:
- эндпоинты (URL-адреса) и HTTP-методы (GET, POST, PUT, DELETE и др.);
- параметры запроса, заголовки, тела запросов и ответов;
- схемы данных в формате JSON Schema;
- аутентификацию (API-ключи, OAuth 2.0, HTTP-схемы);
- контактную информацию, версию и лицензию API.
Файл спецификации обычно называют «контрактом API». Он служит единым источником истины: на его основе генерируются клиентские SDK, серверные заготовки, тесты и документация.
¶Инструменты Swagger
Под брендом Swagger выпускается ряд инструментов:
| Инструмент | Назначение |
|---|---|
| Swagger Editor | Браузный редактор YAML/JSON-описаний с валидацией и предпросмотром |
| Swagger UI | Генерация интерактивной веб-документации из файла спецификации |
| Swagger Codegen | Автогенерация клиентских и серверных заготовок (стабов) на десятках языков |
| Swagger Inspector | Инструмент для тестирования и создания описаний API-запросов |
Swagger UI, вероятно, наиболее узнаваемый компонент: он отображает эндпоинты в виде интерактивного каталога, где можно посмотреть схемы запросов и ответов и отправить тестовый запрос прямо из браузера. В российской практике Swagger UI широко используется в отечественных платформах: например, в API Госуслуг, в документации ряда сервисов Сбера, Яндекса и других крупных компаний.
¶Swagger и OpenAPI: различия
После разделения брендов возникла терминологическая путаница. Строго говоря:
- OpenAPI Specification — открытый стандарт описания API (бывший Swagger Specification);
- Swagger — семейство инструментов SmartBear, работающих с файлами OpenAPI.
Тем не менее в повседневной речи разработчиков «Swagger» нередко используется как синоним самой спецификации, что формально неверно, но широко распространено.
¶Применение
Swagger/OpenAPI применяется в нескольких сценариях:
- Документирование. Автоматическая генерация актуальной документации вместо поддержания её вручную.
- Контрактное проектирование (contract-first). Сначала описывается спецификация, затем по ней пишется код сервера и клиентов.
- Тестирование. Генерация unit- и интеграционных тестов из описания API.
- Валидация. Проверка запросов и ответов на соответствие схеме в рантайме.
- API-шлюзы и мониторинг. Платформы вроде Apigee, Kong или 3scale используют OpenAPI-файлы для настройки политик и мониторинга.
¶Альтернативы
К основным альтернативам OpenAPI относятся:
- RAML (RESTful API Modeling Language) — YAML-основанный язык описания API, проект MuleSoft;
- API Blueprint — формат на основе Markdown от Apiary;
- gRPC + Protocol Buffers — подход Google, ориентированный на RPC вместо REST;
- GraphQL Schema — язык описания для GraphQL-сервисов.
Несмотря на конкуренцию, OpenAPI де-факто стал доминирующим стандартом: поддерживается большинством инструментов разработки, включая Postman, Insomnia, JMeter, а также встроен во многие IDE и CI/CD-конвейеры.
¶Значение
Внедрение OpenAPI/Swagger снизило стоимость поддержки API-контрактов и ускорило интеграцию между командами. По опросам разработчиков, проводимым ежегодно, OpenAPI стабильно входит в тройку самых используемых технологий в области проектирования API. В России спецификация применяется при построении открытых ведомственных API и в коммерческой разработке, что делает её одним из стандартов индустрии.
Источники: документация OpenAPI Initiative (openapis.org), документация SmartBear (swagger.io), RFC 6838, спецификация JSON Schema.