Swagger / OpenAPI

Когда QA говорят «проверь через Swagger», обычно имеют в виду интерактивную страницу Swagger UI. Но основная ценность находится под ней: машиночитаемое описание HTTP API в формате OpenAPI. Оно объясняет доступные операции, входные параметры, ответы и схемы данных. Для тестировщика это отправная точка проверки контракта. Красиво отрисованная документация ещё не доказывает, что сервис соответствует ей, а сам контракт может быть неполным или устаревшим.

OpenAPI и инструменты Swagger

OpenAPI Specification — стандарт описания API. Swagger — семейство инструментов, среди которых Swagger UI отображает описание и позволяет выполнять запросы, а редакторы помогают работать со спецификацией. Версия поля openapi относится к формату документа, версия info.version — к описываемому API. Это разные вещи: изменение документа со стандарта 3.0 на 3.1 не обязательно означает новую бизнес-версию сервиса, и наоборот.

Как читать описание операции

Начни с метода и пути, затем проверь параметры path/query/header, requestBody, ответы и требования безопасности. В components обычно находятся переиспользуемые схемы. Посмотри required, ограничения длины и диапазона, допустимые enum, варианты oneOf и ссылки $ref. Обязательность тела запроса и обязательность отдельного свойства задаются на разных уровнях. Если QA читает только пример JSON, он легко пропускает ограничения, которые в примере никак не проявляются.

Версия схемы имеет значение

На октябрь 2026 года опубликована OpenAPI 3.2.1, однако проект может обоснованно использовать другую версию. Проверяй совместимость валидатора, генератора клиентов и используемых ключевых слов. Например, правила представления nullable различаются между ветками 3.0 и 3.1. Не меняй синтаксис по памяти из случайного руководства. Для воспроизводимого анализа сохрани конкретную версию спецификации вместе со сборкой сервиса и результатами валидации; ссылка на постоянно меняющийся документ быстро теряет доказательную ценность.

От схемы к тестовым данным

Пусть POST /orders принимает quantity, целое число от 1 до 10, и sku, непустую строку. По контракту успешное создание возвращает 201 с id и quantity. Из этого следуют проверки минимального и максимального значений, соседних недопустимых значений, пропущенного quantity, строки вместо числа и отсутствующего sku. Но ещё нужны бизнес-правила: существует ли товар, хватает ли остатка, может ли пользователь оформлять заказ. Структура запроса не описывает эти условия автоматически.

Небольшой фрагмент схемы показывает разницу между объявленным полем и обязательным полем. Это часть документа, а не полноценная спецификация готового API.

yaml

type: object
required:
  - sku
  - quantity
properties:
  sku:
    type: string
    minLength: 1
  quantity:
    type: integer
    minimum: 1
    maximum: 10

Практика: проверить контракт заказа

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

1.Отправь quantity=1 и quantity=10. Ожидаются успешное создание и ответы, соответствующие описанным типам и обязательным свойствам.
2.Отправь 0, 11, 1.5 и строку "2" отдельными запросами. Ожидание бери из контракта; если приведение типов разрешено, строка не обязательно дефект.
3.Удали quantity из тела. Ожидается согласованная ошибка обязательного поля, а не молчаливая подстановка, которой нет в требованиях.
4.Проверь заголовок Content-Type и структуру ошибки. Успешная схема ответа не должна применяться к ошибочному ответу.
5.Прочитай созданный заказ другим запросом. Валидный ответ создания не доказывает, что сервер сохранил правильные данные.

Security scheme не заменяет проверку прав

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

Что означает расхождение документа и сервиса

Если схема требует строковый id, а сервер возвращает число, зафиксируй расхождение. Дальше вместе с владельцем API выясни источник истины: ошибочна реализация или документ. Не «исправляй» тест простым ослаблением проверки. Если оба артефакта генерируются из одного кода, они могут согласованно повторять одну ошибку; независимые требования и сценарии потребителя всё ещё нужны. Формальная валидация полезна, но не исчерпывает тестирование интеграции.

Проверь также семантику пустоты: отсутствующее свойство, пустая строка, пустой массив и null могут означать разные действия. Для PATCH это особенно заметно: пропущенное поле иногда означает «оставить прежнее», а null — «очистить», если так устроен контракт. Подготовь существующий объект с известными значениями и проверь каждую форму отдельно, затем прочитай результат. Схема помогает определить допустимость входа, а требования объясняют изменение состояния. Если описание не отвечает на этот вопрос, зафиксируй пробел до разработки тестового ожидания. Такая работа с неоднозначностью полезнее, чем спор о том, какой ответ выглядит привычнее конкретному тестировщику.

Совместимость и изменения контракта

Удаление поля, сужение enum, новый обязательный параметр и изменение типа часто ломают клиентов. Добавление нового поля тоже оценивают с учётом строгости потребителей. Сравнивай версии спецификации в review и отдельно проверяй критичные клиенты. Для optional-поля важно поведение старого клиента без него, а для deprecated-операции — согласованный срок и путь перехода. Один успешный вызов новой версии не подтверждает обратную совместимость всей интеграции.

Типичные ошибки и практический вывод

Частые ошибки — тестировать только примеры, путать required со свойством properties, считать кнопку выполнения безопасной на любом server и открывать внутреннюю спецификацию во внешнем сервисе без проверки состава данных. Swagger UI выполняет реальные запросы и зависит от браузерной среды, включая CORS. Качественная работа QA даёт набор проверок контракта, отдельно отмеченные бизнес-риски и подтверждённые расхождения. Документ становится рабочим соглашением между командами, когда его проверяют вместе с реальным сервисом.