← Назад к блогу

LLM для аналитика · 5 минут

Контракт API и примеры расходятся: как найти ошибку до написания клиента

Когда пример JSON не соответствует контракту API, нельзя автоматически считать правильным ни пример, ни схему.

Когда пример JSON не соответствует контракту API, нельзя автоматически считать правильным ни пример, ни схему. Сначала зафиксируйте расхождение с точным путём поля. Затем владелец API должен определить, исправляется документация или меняется контракт. LLM может подготовить такую сверку, но валидация должна выполняться отдельно.

В учебном ответе заказа четыре ошибки: тип id, значение status, тип total и лишнее поле. Схема и JSON ниже позволяют воспроизвести каждую по отдельности.

Контракт ответа и спорный пример

Договоримся, что ответ создания заказа — объект с обязательными id, status и total. id — строка, status — одно из new, paid, total — целое неотрицательное число копеек. Необъявленные поля запрещены. Это правила нашего синтетического контракта, а не универсальные правила платежных API.

{
  "type": "object",
  "required": ["id", "status", "total"],
  "additionalProperties": false,
  "properties": {
    "id": {"type": "string"},
    "status": {"type": "string", "enum": ["new", "paid"]},
    "total": {"type": "integer", "minimum": 0}
  }
}

Спорный пример из условной документации:

{"id": 42, "status": "processing", "total": "1500", "discount": 10}

Четыре независимых расхождения

ПутьВ примереОграничениеВывод
/idЧисло 42СтрокаНеверный тип
/statusprocessingnew или paidЗначение вне enum
/totalСтрока «1500»Целое число от нуляНеверный тип
Корень, discountДополнительное полеadditionalProperties falseПоле не разрешено

Не объединяйте эти замечания в «JSON невалиден». Сам JSON синтаксически корректен. Он невалиден относительно выбранной схемы. Если разработчик видит только общую ошибку, он может исправить id и не заметить остальные три проблемы.

Исправленный пример и смысл исправления

{"id": "42", "status": "new", "total": 1500}

Этот объект соответствует схеме, однако изменение processing на new требует внимания. Валидатор доказывает допустимость new, но не доказывает, что реальный заказ находится именно в этом состоянии. В учебном примере new выбран автором; для реальных данных состояние нужно получить из надёжного источника, а не подобрать из enum.

Поле discount удалено потому, что наша схема его запрещает. Если клиенты используют скидку, исправление примера может скрыть несовместимость документации. Тогда вопрос владельцу API звучит так: «discount ошибочно попало в пример или отсутствует в контракте?» До ответа нельзя считать задачу закрытой.

Как локализовать ошибку без гадания

Сначала проверьте исходный спорный объект целиком. Затем сформируйте четыре отдельных контрпримера из корректного объекта: числовой id, неизвестный status, строковый total и лишний discount. Каждый должен нарушать ровно одно выбранное правило.

Валидатор jsonschema 4.23.0 нашёл в исходном объекте четыре нарушения. Исправленный объект прошёл проверку, а каждый одиночный контрпример нарушил одно ограничение. Машинный отчёт содержит пути полей и сообщения валидатора. Обратную совместимость сервиса нужно проверять отдельно на его потребителях.

Что передать разработчику и владельцу API

Передайте версию контракта, JSON Pointer проблемного поля, исходный пример, результат валидатора и предложенную правку. Отдельно укажите спорные семантические изменения: status и discount. Иначе техническое исправление документа может выглядеть как согласованное бизнес-решение.

Если схема находится в OpenAPI, привяжите замечание к операции и конкретной версии документа. Спецификация OpenAPI 3.0.3 полезна для проверки используемого диалекта; не смешивайте без проверки возможности разных версий Schema Object и JSON Schema.

Два решения остаются за владельцем API: какой статус описывает пример и нужно ли поле discount в контракте. Зафиксируйте ответы до правки документации. Затем используйте исправленный объект как базовый для граничных и негативных тестов.

Вопросы по разбору

Спорный пример содержит синтаксическую ошибку JSON?

Нет. JSON корректно разбирается, но нарушает четыре ограничения схемы. Синтаксическая валидность и соответствие контракту — разные проверки.

Почему discount считается ошибкой?

Схема запрещает необъявленные свойства через additionalProperties false. Если поле нужно потребителям, владелец API должен решить вопрос изменения контракта.

Можно ли заменить processing на любое значение enum?

Валидатор примет допустимое значение, но оно должно соответствовать состоянию заказа. В учебном исправлении new выбран автором.

Зачем нужны одиночные контрпримеры?

Они изолируют тип id, enum status, тип total и дополнительное поле. После одной правки можно убедиться, что остальные проверки тоже работают.

Что приложить к замечанию владельцу API?

Версию схемы, путь поля, исходный пример, сообщение валидатора и предложенную правку. Семантические изменения status и discount выделите отдельно.

Автор: Иннокентий Бодров, автор Аналитической мастерской.