Для чего используется Swagger
Что проверяют
Понимаете ли вы, что это контракт, а не просто красивая документация.
Как отвечать
OpenAPI это формальное описание REST API в формате YAML или JSON: пути, методы, параметры, схемы тел запроса и ответа, коды состояния, схемы авторизации, примеры.
Ключевое слово тут контракт. Из одного описания вырастает целое семейство применений:
- документация: Swagger UI рисует интерактивную страницу, где запрос можно отправить прямо из браузера;
- генерация клиентов: типизированный клиент для фронтенда или другого сервиса собирается автоматически, и расхождение с сервером ловится на этапе сборки, а не в проде;
- генерация заготовок сервера и заглушек, чтобы потребитель начал работу до готовности бэкенда;
- валидация: шлюз или промежуточный слой проверяет запросы и ответы на соответствие схеме;
- тестирование: описание импортируется в Postman, а автотесты проверяют ответ на соответствие схеме, что ловит незаявленные изменения формата.
Два подхода к работе стоит различать:
- сначала код: описание генерируется из аннотаций в исходниках. Проще для одной команды, но описание всегда отстаёт и повторяет реализацию, включая её ошибки;
- сначала описание: контракт согласуется до написания кода, потребители сразу начинают работать с заглушками. Дороже на старте, но избавляет от переделок на стыке команд.
Про версии: третья ветка сильно отличается от второй, которую по привычке называют Swagger. Swagger сегодня это набор инструментов, а сам формат называется OpenAPI.
Для тестировщика это ещё и источник тест-кейсов: обязательные поля, форматы, перечисления допустимых значений и коды ошибок уже перечислены, остаётся проверить, что реальность им соответствует.
Где спотыкаются
Считают OpenAPI просто способом сгенерировать документацию.
Держат описание отдельно от кода, и оно устаревает.
Не проверяют ответы на соответствие схеме в тестах.
Путают формат и набор инструментов вокруг него.