API используют для обмена данными между сервисами: например, интернет-магазин через API может обращаться к платежной системе или службе доставки. Чтобы разработчики и тестировщики понимали, какие запросы поддерживает API и какие данные он возвращает, интерфейс нужно описать. Для этого используют Swagger. Разберем, как он устроен и как с ним работать.
Что такое Swagger
Swagger — это семейство инструментов для работы с документацией программного интерфейса приложения (API). С их помощью можно создавать и редактировать описание API, отображать его в удобном виде, отправлять тестовые запросы и генерировать заготовки кода.
В основе Swagger лежит спецификация OpenAPI — формальное описание API. В ней фиксируют:
- какие операции поддерживает сервис;
- по каким адресам отправлять запросы;
- какие параметры и данные нужно передавать;
- какие ответы может вернуть сервер;
- какие ошибки предусмотрены;
- как устроена авторизация.
Например, в спецификации API интернет-магазина можно указать, что для получения информации о заказе нужно отправить его номер по определенному адресу. Там же описывают структуру успешного ответа и ошибку, которую вернет сервер, если заказ не найден.
На основе такого описания Swagger UI формирует интерактивную документацию, Swagger Editor позволяет редактировать и проверять спецификацию, а Swagger Codegen — создавать по ней программные заготовки.
Без единого описания сведения об API могут оказаться распределены между кодом, отдельными документами и перепиской. Спецификация дает разработчикам, тестировщикам и аналитикам общий контракт, на который они могут опираться при разработке и интеграции.
Чем Swagger отличается от OpenAPI
Названия Swagger и OpenAPI часто используют как синонимы, хотя они обозначают разные вещи.
OpenAPI — это стандарт, по которому составляют формальное описание API. Swagger — набор инструментов для работы с таким описанием: в него входят Swagger UI, Swagger Editor и Swagger Codegen.
Раньше название Swagger относилось и к самой спецификации. Позднее стандарт передали OpenAPI Initiative. Поэтому сегодня корректнее говорить «спецификация OpenAPI», хотя выражение «Swagger-документация» по-прежнему широко распространено.
Как Swagger работает с REST API
Чаще всего Swagger используют для документации REST API. Такой интерфейс позволяет получать, создавать, изменять и удалять данные с помощью стандартных HTTP-методов.
Например, через API интернет-магазина можно получить список товаров, открыть карточку товара, создать или отменить заказ.
Каждой операции соответствует определенный адрес сервиса (endpoint). Его можно представить как отдельную точку входа в систему. Swagger показывает, какие адреса существуют, какие данные они принимают и какой результат возвращают.
При этом Swagger только фиксирует устройство API. Он не исправляет архитектуру автоматически, но помогает обнаруживать противоречия и неточности в описании интерфейса.
Из чего состоит OpenAPI-спецификация
OpenAPI-спецификацию обычно составляют в формате YAML или JSON. В ней описывают, как именно клиент может обращаться к API.
Например, для получения информации о заказе спецификация может задавать адрес /orders/{id} и метод GET. В ней указывают, что id — обязательный параметр с номером заказа, а также описывают возможные ответы сервера: 200, если заказ найден, и 404, если заказа с таким номером нет.
Отдельно в спецификации можно описать структуру самого заказа — например, поля с его номером, статусом и датой доставки. Такую схему не нужно заново прописывать для каждой операции: на нее можно ссылаться в разных частях документа.
Там же задают способ авторизации и адреса серверов для тестовой и рабочей среды. В результате в одном файле зафиксировано, какие операции доступны, какие данные нужно передать и какие ответы может вернуть API.
Swagger UI
Swagger UI превращает технический файл OpenAPI в интерактивную веб-страницу. Пользователь видит список методов, параметры, схемы данных, примеры и возможные ответы.
Через функцию Try it out можно заполнить параметры и отправить реальный запрос прямо из браузера. Например, тестировщик может ввести номер заказа и посмотреть, какой ответ вернет сервер.
Swagger UI подходит для знакомства с сервисом и быстрых ручных проверок. Однако он не заменяет автоматические тесты, нагрузочное тестирование и проверку сложных пользовательских сценариев.
Swagger Editor
Swagger Editor — редактор для создания и проверки OpenAPI-документа. В одной части экрана пользователь пишет описание, а в другой сразу видит готовую документацию. Если в структуре допущена ошибка, редактор подсвечивает проблемное место.
Инструмент позволяет создавать спецификацию, редактировать существующий документ, находить технические ошибки и обсуждать контракт до начала разработки. Однако редактор не может оценить, насколько понятны названия полей и соответствует ли описание реальному бизнес-процессу.
Swagger Codegen
Swagger Codegen создает по OpenAPI-спецификации заготовки программного кода: например, клиент для обращения к API, модели данных или основу серверного приложения.
Это не готовый продукт, а шаблон, который разработчик должен дополнить бизнес-логикой и настройками. Инструмент выполняет повторяющиеся операции, но не заменяет проектирование и разработку.
Спецификацию также можно использовать для генерации набора средств разработки (SDK), документации и отдельных тестов.
Как Swagger используют разные специалисты
Разработчик серверной части получает точный контракт: какие операции должны существовать, какие параметры они принимают, какие ответы возвращают и какие ошибки необходимо предусмотреть.
Swagger также помогает находить несовместимые изменения. Например, если разработчик удалил поле, которое уже использует мобильное приложение, проверка спецификации может выявить проблему до выхода новой версии.
Разработчик клиентской части видит структуру запросов и ответов, названия полей, форматы данных и возможные ошибки. Если контракт согласован заранее, клиентскую часть можно разрабатывать до полной готовности сервера: подготовить интерфейс, временные данные и клиент для будущей интеграции.
Инженер по тестированию получает перечень методов, параметров, ограничений и кодов ответа. По ним он составляет позитивные и негативные сценарии, а через Swagger UI выполняет быстрые ручные проверки.
Системный аналитик фиксирует, как разные системы должны обмениваться данными: какие поля обязательны, какие ограничения действуют и какие ошибки возможны.
При этом Swagger не заменяет всю аналитическую документацию. Сложные бизнес-процессы и пользовательские сценарии обычно требуют дополнительных схем и пояснений.
Подходы к разработке API: code-first и contract-first
Существует два основных подхода к работе с API.
При code-first команда сначала пишет программный код, а затем создает документацию. Такой подход часто используют для небольших внутренних сервисов и прототипов. Его риск в том, что документация может начать отставать от реализации.
При contract-first сначала создают и согласуют спецификацию, а уже затем разрабатывают серверную и клиентскую части.
Contract-first особенно полезен, если с API работают несколько команд, мобильное приложение, партнеры или внешние интеграторы. Разработчики серверной и клиентской частей могут работать параллельно, опираясь на один контракт.
На практике команды могут сочетать оба подхода. Главное — поддерживать спецификацию в актуальном состоянии.
Как начать работу со Swagger
Работу можно выстроить следующим образом:
- Определить пользователей API и основные сценарии.
- Выбрать одну операцию и описать ее назначение.
- Указать адрес сервиса, метод и параметры.
- Описать успешный ответ и возможные ошибки.
- Добавить правила авторизации.
- Проверить документ в Swagger Editor.
- Опубликовать его через Swagger UI.
- Согласовать контракт с командой.
- Сохранить спецификацию рядом с кодом.
- Добавить автоматическую проверку изменений.
Также нужно определить, кто в команде отвечает за актуальность документации.
Для работы API и Swagger UI нужна инфраструктура, на которой будут запущены соответствующие компоненты. Если проект находится в разработке или требует отдельных сред для тестирования и рабочего запуска, можно использовать облачные серверы Рег.облака, которые позволяют развернуть необходимые компоненты проекта без покупки собственного оборудования.
Типичные ошибки при работе со Swagger
Главная ошибка — не обновлять документацию вместе с API. Тогда спецификация расходится с реальной работой сервиса и вводит команду в заблуждение.
Также в описании нередко указывают только успешный ответ, забывают про ошибки, обязательные поля, ограничения и авторизацию. Примеры могут не соответствовать схемам, а тестовый и рабочий серверы — быть перепутаны.
Чтобы избежать таких проблем, спецификацию нужно хранить рядом с кодом, обновлять при изменениях и автоматически проверять в CI/CD.
Безопасность Swagger UI
Swagger UI показывает структуру API, внутренние методы и параметры, поэтому доступ к документации нужно настраивать с учетом того, для кого она предназначена.
Для публичного API открытая документация может быть частью продукта. Для внутренних сервисов доступ можно ограничить с помощью авторизации, виртуальной частной сети (VPN), фильтрации по IP-адресам или отдельной тестовой среды.
В примеры запросов и ответов для Swagger UI не стоит подставлять реальные пароли, токены и персональные данные. Для внутренней документации также нужно отдельно определить, кому доступен Swagger UI и можно ли через него отправлять запросы.
Swagger в процессе разработки
В современных проектах OpenAPI-файл обычно хранят в одном репозитории с кодом. При каждом изменении автоматическая система может проверять корректность документа и выявлять изменения, способные нарушить работу существующих клиентов.
API-сервисы, серверные приложения и Swagger UI необходимо размещать на серверной инфраструктуре. Для разработки, тестирования, staging-среды или запуска проекта в production можно использовать облачные серверы Рег.облака. Они позволяют развернуть нужные компоненты проекта и выделить отдельные среды для разных этапов разработки.
После проверки документацию можно автоматически публиковать на внутреннем портале или в Swagger UI.
Спецификацию также можно использовать для настройки API-шлюзов, mock-сред, каталогов сервисов и генерации клиентских библиотек. Конкретные возможности зависят от выбранной платформы.
Заключение
Swagger помогает поддерживать единое описание API для разработчиков, тестировщиков и аналитиков. Swagger UI отображает документацию в интерактивном виде, Swagger Editor позволяет создавать и проверять спецификацию, а Swagger Codegen — генерировать программные заготовки.
При этом основой остается OpenAPI-спецификация — контракт, в котором зафиксированы доступные операции, параметры, структура данных, ответы и ошибки. Чтобы такой контракт оставался полезным, его нужно обновлять вместе с API и проверять при изменениях.
Часто задаваемые вопросы
Что такое Swagger?
Swagger — набор инструментов для создания, просмотра и использования документации API.
Чем Swagger отличается от OpenAPI?
OpenAPI — стандарт описания API, а Swagger — набор инструментов для работы с этим стандартом.
Что такое Swagger UI?
Swagger UI превращает OpenAPI-спецификацию в интерактивную веб-страницу с методами, параметрами, примерами запросов и ответов.
Что такое Swagger Editor?
Это редактор для создания и проверки OpenAPI-спецификаций.
Что описывает Swagger?
В спецификации фиксируют адреса сервисов, методы, параметры, структуру запросов и ответов, возможные ошибки и правила авторизации.
Можно ли тестировать API через Swagger?
Да. Swagger UI позволяет отправлять реальные запросы из браузера, но не заменяет полноценное тестирование API.
Что такое OpenAPI-спецификация?
Это структурированное описание API, которое могут использовать как специалисты, так и программные инструменты.
Что лучше использовать — YAML или JSON?
Оба формата поддерживают описание OpenAPI. YAML обычно удобнее читать и редактировать вручную, а JSON широко используется для программной обработки.
Кому полезен Swagger?
Разработчикам серверной и клиентской частей, инженерам по тестированию, аналитикам, архитекторам и интеграторам.
Какие ошибки чаще всего допускают при работе со Swagger?
Не обновляют спецификацию вместе с API, не описывают ошибки и ограничения, используют устаревшие примеры и не указывают правила авторизации.
При изменении API нужно учитывать уже работающие интеграции. Например, если удалить из ответа поле, которое использует мобильное приложение, клиент может перестать корректно обрабатывать данные. Проверка OpenAPI-спецификации помогает обнаружить такие несовместимые изменения до выпуска новой версии.