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

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 из таблицы нужно отдельно сверить с работающим сервисом.

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