LLM для аналитика · 5 минут
OpenAPI в таблицу ошибок и граничных случаев: как не выдумать поведение API
Чтобы получить из OpenAPI таблицу ошибок и граничных случаев, извлеките ограничения входа и объявленные ответы отдельно.
Чтобы получить из OpenAPI таблицу ошибок и граничных случаев, извлеките ограничения входа и объявленные ответы отдельно. Отсутствие поля и неверный тип позволяют построить негативные входы. Но конкретный код ответа нельзя считать установленным, если контракт его не определяет для этого случая.
В учебном API сумма заявки ограничена диапазоном от 1 до 10 000, а валюта — двумя значениями. Из этих ограничений получим входы для тестов. Работающего сервиса у примера нет: HTTP-ответы предстоит проверить при интеграции.
Минимальная операция
В примере используется OpenAPI 3.0.3. Фрагмент принадлежит документу с openapi: 3.0.3, info и путём /requests. Он показывает значимые для разбора поля, а не полный файл спецификации.
post:
operationId: createRequest
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [amount, currency]
additionalProperties: false
properties:
amount:
type: integer
minimum: 1
maximum: 10000
currency:
type: string
enum: [RUB, EUR]
responses:
'201':
description: Заявка создана
'400':
description: Невалидное тело запросаВ OpenAPI 3.0.3 объект запроса и схема описывают разные уровни обязательности. Здесь требуется и само тело, и два поля внутри него. Для этой учебной операции описание 400 связывает ответ с невалидным телом; на реальном сервисе соответствие ещё нужно проверить.
Таблица из явных ограничений
| Проверка | Вход | Ожидаемый результат по контракту |
|---|---|---|
| Нижняя граница | amount 1, currency RUB | Валидное тело; штатный ответ создания 201 |
| Верхняя граница | amount 10000, currency EUR | Валидное тело; штатный ответ создания 201 |
| Ниже диапазона | amount 0, currency RUB | Невалидное тело; заявлен 400 |
| Выше диапазона | amount 10001, currency RUB | Невалидное тело; заявлен 400 |
| Нет валюты | amount 1 | Невалидное тело; заявлен 400 |
| Неизвестная валюта | amount 1, currency USD | Невалидное тело; заявлен 400 |
| Неверный тип | amount «1», currency RUB | Невалидное тело; заявлен 400 |
| Лишнее поле | amount 1, currency RUB, urgent true | Невалидное тело; заявлен 400 |
Проверяйте поля независимо: нельзя передать одновременно нулевую сумму и неизвестную валюту, а затем считать обе проверки выполненными по одному ответу. Для негативного случая меняйте одно свойство корректного базового запроса.
Валидность тела не гарантирует успешного создания: сервер может быть недоступен. Таблица описывает штатный сценарий и контрактную обработку невалидного тела, а не обещание фактического ответа при любом состоянии инфраструктуры.
Что нельзя вывести из этого фрагмента
Здесь не определены аутентификация, повторная отправка, rate limit и сохранение заявки после таймаута. Поэтому 401, 403, 409, 429 и правило автоматического retry не входят в доказанные требования. Их можно включить в раздел вопросов, но нельзя приписать исходнику.
Также не задана структура ответа 201. До разработки клиента нужно уточнить, возвращается ли идентификатор, где его искать и как выглядит ошибка. Проверка одного HTTP-кода не проверит данные созданной заявки.
Как использовать LLM и проверить результат
Попросите модель возвращать для каждого случая operationId, путь к ограничению, изменённое поле и ожидаемый исход. Требуйте отдельный список UNKNOWN: отсутствующие ответы, неописанные заголовки, правила повторов. Если модель пишет «при дубле 409», найдите источник этого утверждения. В нашем фрагменте его нет.
Валидатор jsonschema 4.23.0 принял оба граничных значения и отклонил все шесть негативных входов. Отчёт проверки схемы показывает результат каждого случая. Эти проверки не отправляют запросы в API.
Перед интеграционным тестом запросите схему ответа 201, формат ошибок и правила повторной отправки. Проверьте, что документация содержит примеры, совместимые с контрактом. После этого к восьми входам можно добавить проверки ответа сервера.
Вопросы по разбору
Как получить граничные случаи из OpenAPI?
Найдите minimum, maximum, required и enum. Для amount в примере это 1, 10000 и два соседних недопустимых значения: 0 и 10001.
Можно ли добавить ожидаемый 409 для дубликата?
В приведённой операции такое поведение не описано. Добавьте вопрос владельцу API вместо неподтверждённого ожидания.
Один запрос с двумя ошибками проверяет обе?
Он не позволяет надёжно локализовать каждую проверку. Меняйте одно свойство корректного базового запроса за раз.
Обязательное тело делает все поля обязательными?
Нет. required у requestBody относится к телу, а список required в schema — к отдельным свойствам объекта.
Валидация схемы проверяет ответ HTTP?
Нет. Она проверяет данные по ограничениям. Коды 201 и 400 из таблицы нужно отдельно сверить с работающим сервисом.
Автор: Иннокентий Бодров, автор Аналитической мастерской.