API-документация не соответствует реальному ответу: как синхронизировать контракт

Расхождение может быть в типе поля, nullable, имени, вложенности, коде ответа, формате ошибки или обязательности заголовка. Даже визуально похожий JSON ломает сгенерированный клиент, если документация обещает число, а production иногда возвращает строку или null.

Сохраните обезличенный реальный response вместе с URL, методом, status code, content type и версией сервиса. Проверьте его валидатором против конкретной опубликованной OpenAPI-схемы. Не исправляйте пример вручную, пока не решено, контракт неверен или реализация нарушила обещание.

Что проверить в первую очередь

Для проблемы «описанная схема API расходится с фактическим HTTP-ответом» сначала зафиксируйте один воспроизводимый пример: точное время, идентификатор объекта, пользователя или операции, входные данные, версию приложения и фактический результат. Отдельно запишите ожидаемое поведение: исполняемый контракт, реализация, примеры и клиентские модели проверяются автоматически и меняются в одном управляемом процессе с версионированием. Это не формальность. Без исходной точки легко принять временное совпадение за исправление, изменить сразу несколько условий и потерять возможность доказать настоящую причину сбоя.

Проверку начинайте с чтения состояния и журналов. Не запускайте массовый перерасчёт, повторную отправку, удаление записей или изменение прав на рабочей системе, пока не подготовлены резервная копия и способ отката. Секреты, токены, персональные данные и содержимое заказов в диагностические выгрузки не включайте.

• Уточните версию спецификации и endpoint, которому она соответствует.
• Сравните status code, заголовки и тело, включая ошибочные ответы.
• Проверьте required, nullable, enum, format и additionalProperties.
• Убедитесь, что gateway и serializer не меняют форму после приложения.
• Соберите примеры для разных ролей, пустых списков и частичных данных.

Почему возникает проблема

Видимый симптом обычно находится в конце цепочки. Пользователь видит неверный статус или отказ, хотя первичная ошибка могла произойти в API, фоновой задаче, кеше, очереди, внешнем сервисе либо при проверке доступа. Основной риск этого сценария: клиенты падают, неверно интерпретируют поля или генерируют несовместимый SDK, а разработчики не понимают, чему доверять. Поэтому исправление только интерфейса или ручная правка итоговой записи часто скрывает проблему, но не устраняет её.

Разбирайте события по хронологии и ищите первую точку, где фактические данные перестают соответствовать бизнес-правилу. В распределённой системе одинаково важны успешный ответ, повтор запроса, задержка события, параллельное выполнение и восстановление после временного отказа.

• OpenAPI поддерживается вручную и не обновляется вместе с кодом.
• Аннотации генерации не учитывают кастомный serializer.
• Несколько версий backend обслуживают один URL во время rollout.
• Поле добавлено как обязательное без версии и миграционного периода.
• Примеры скопированы из старой модели и не проходят schema validation.

Пошаговая диагностика

Создайте безопасный тестовый сценарий, максимально похожий на проблемный, но не затрагивающий реальные списания, рассылки и клиентские данные. Присвойте операции единый correlation ID и проследите его через входящий запрос, бизнес-логику, базу, очередь и внешние интеграции. Для каждого этапа фиксируйте вход, результат, код ответа, время выполнения и номер версии записи.

Сначала подтвердите сам факт расхождения, затем последовательно исключайте уровни. Сравните рабочий и ошибочный случаи по одним и тем же полям. Проверьте часовой пояс, формат идентификаторов, порядок событий, права сервисной учётной записи и актуальность конфигурации на каждом экземпляре приложения. Если результат зависит от повторного запроса, задержки или конкретного узла, это важная часть причины, а не случайный шум.

• Прогоните реальные безопасные ответы через валидатор схемы.
• Сравните commit или build ID backend с датой публикации спецификации.
• Проверьте ответы на каждом экземпляре либо регионе.
• Соберите consumer contract tests критичных клиентов.
• Просмотрите diff OpenAPI на breaking changes до и после релиза.

Как сделать контракт исполняемым

Спецификация должна быть частью версии продукта и проверяться в CI. Источник правды может идти от схемы к коду или от типизированного кода к схеме, но ручное независимое редактирование обоих источников почти неизбежно создаёт дрейф.

Надёжная реализация хранит бизнес-состояние явно и не пытается восстановить его только по экрану, случайному логу или последнему webhook. У каждого значимого действия должен быть стабильный идентификатор, понятный владелец, версия правила и проверяемый переход статуса. Повторная доставка одного события не должна создавать второе действие, а запоздавшее событие не должно возвращать объект в невозможное состояние.

• Каждый release публикует версионированную спецификацию с build metadata.
• Response validation работает в тестах и выборочно в non-production.
• Примеры генерируются или проверяются той же схемой.
• Breaking changes требуют новой версии или согласованного переходного периода.
• Критичные consumers закрепляют ожидания контрактными тестами.

Как исправить проблему

Исправление разделите на небольшие обратимые изменения. Сначала устраните подтверждённую первопричину, затем восстановите повреждённые данные отдельной контролируемой процедурой. Не смешивайте выпуск нового кода и массовую коррекцию истории в одном непрозрачном запуске: для них нужны разные отчёты, критерии успеха и планы отката.

Если затронуты существующие записи, сначала сформируйте dry-run: список объектов, старое значение, предлагаемое новое значение и основание для изменения. Обновление должно быть идемпотентным, ограниченным точной выборкой и сопровождаться аудитом. Для финансовых данных, прав доступа и персональной информации предпочтительны компенсирующие записи, а не переписывание истории.

• Выберите один генеративный источник правды и удалите дублирующие ручные схемы.
• Добавьте validation успешных и ошибочных ответов в интеграционные тесты.
• Исправьте типы и nullable с учётом уже работающих клиентов.
• Версионируйте несовместимое изменение вместо тихой подмены.
• Публикуйте спецификацию только из того же артефакта, который развёрнут в среде.

Безопасный порядок внедрения

• Сохраните конфигурацию, связанные записи и необходимые журналы; отдельно проверьте, что резервную копию действительно можно восстановить.
• Воспроизведите проблему на тестовом объекте и сохраните результат до изменения, чтобы после выпуска сравнить одинаковые сценарии.
• Внесите минимальное изменение под системой контроля версий, опишите причину, ожидаемый эффект, ограничения и точный способ отката.
• Прогоните нормальный сценарий, ошибочный ввод, повтор одного запроса, два параллельных запроса и временную недоступность зависимости.
• Выпустите изменение на ограниченную долю трафика или один процесс, если архитектура это позволяет, и сравните метрики со старой версией.
• Только после стабильного наблюдения выполните контролируемое исправление исторических данных и сохраните итоговый отчёт.

Как проверить результат

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

Критерии приёмки сформулируйте до выпуска. Каждый пункт должен давать однозначный ответ «выполнено» или «не выполнено», а не субъективную оценку. Если тест невозможно повторить автоматически, оставьте короткий регрессионный чек-лист с тестовыми данными и ожидаемыми статусами.

• Каждый пример из документации проходит актуальную схему.
• Реальные ответы критичных endpoint валидируются для пустых и заполненных данных.
• Старый клиент продолжает работать в пределах заявленной версии.
• Canary и основной rollout возвращают совместимую форму.
• Ошибочные ответы имеют стабильный content type, code и структуру.

Типичные ошибки при исправлении

• Исправлять только Swagger UI, не меняя источник публикации.
• Делать новое поле required без переходного периода.
• Проверять только HTTP 200 и игнорировать ошибки.
• Считать JSON Schema полной заменой семантических бизнес-правил.
• Публиковать latest без связи с конкретной версией backend.

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

Как предотвратить повторение

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

Настройте мониторинг полного пользовательского пути, а не только доступности отдельных серверов. Техническая метрика должна быть связана с бизнес-результатом: заказ завершён, доступ выдан, файл восстановлен, событие обработано один раз, данные изолированы. Порог оповещения задавайте по нормальному профилю нагрузки и проверяйте, что уведомление содержит достаточно контекста для первого решения.

• Ошибки schema validation по endpoint и версии сервиса.
• Breaking changes в OpenAPI diff до релиза.
• Клиентские ошибки десериализации и неизвестные enum.
• Возраст опубликованной спецификации относительно production build.
• Покрытие критичных consumer contract tests.

Что подготовить для технического разбора

• Короткое описание ожидаемого и фактического поведения с точной последовательностью действий.
• Время возникновения, идентификатор тестового объекта и версии всех затронутых компонентов.
• Обезличенные фрагменты журналов до и после ошибки с единым correlation ID.
• Список последних изменений, результаты уже выполненных проверок и условия, при которых симптом исчезает.
• Безопасный доступ к тестовой среде либо минимальный пример, не содержащий паролей, токенов и персональных данных.

Частые вопросы

Что считать источником правды?

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

Можно ли добавлять новые поля без версии?

Часто можно как совместимое изменение, если клиенты допускают неизвестные поля; это нужно подтвердить контрактами.

Нужно ли валидировать production-ответы?

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

Когда нужна помощь специалиста

Если OpenAPI расходится с реальным API, я могу определить источник дрейфа, добавить schema и consumer tests и настроить безопасное версионирование. Для оценки нужны спецификация, обезличенный request и response и версия backend.