Можно ли всегда доверять Swagger документации после обновления сервиса

Что проверяют

Относитесь ли вы к документации как к ещё одному артефакту, который тоже нужно тестировать. Хороший ответ звучит как «нет, и вот как я это проверяю». Следом спрашивают, как вы узнаете, что обновление сломало контракт для клиентов.

Как отвечать

Начните с того, откуда берётся спецификация, от этого зависят риски:

• code-first: OpenAPI генерируется из кода и аннотаций (springdoc, FastAPI, Swashbuckle). Сигнатуры эндпоинтов обычно совпадают с реальностью, но описания, примеры, коды ошибок и ограничения полей живут в аннотациях, и их забывают обновить. Бизнес-правила вроде «поле обязательно при оплаченном статусе» в схему не попадают вовсе;
• design-first: спецификацию пишут руками до реализации. Расхождение с кодом здесь вопрос времени, если в CI нет проверки.

Что сверять после релиза: обязательность полей и nullable, допустимые значения enum, коды ответов (200 против 201, 400 против 422), формат дат, поля, которые пришли в ответе, но не описаны. И отдельно: с какого стенда открыт Swagger UI, потому что спецификация на тестовом стенде и на проде может отличаться версией.

Инструменты, которые снимают рутину:

• валидация в автотестах: фильтр OpenApiValidationFilter из swagger-request-validator подключается к REST Assured и сверяет каждый ответ со спецификацией;
• Schemathesis: генерирует запросы по OpenAPI и ловит ответы, не соответствующие схеме, включая пятисотые на граничных данных;
• сравнение версий спецификации: oasdiff или openapi-diff в CI показывают ломающие изменения, например удалённое поле или новый обязательный параметр;
• контрактные тесты: Pact, если у API несколько потребителей и важно, что именно они используют.

Где спотыкаются

Берут Swagger как ожидаемый результат теста. Тогда тест подтверждает документацию, а не требования, и ошибка в спецификации превращается в «правильное» поведение.

Проверяют только успешные сценарии. Коды и тела ошибок расходятся с документацией чаще всего, а клиенты завязаны именно на них.

Не сверяют версию. Смотрят спецификацию с одного стенда, тестируют другой и тратят день на несуществующий баг.