44 lines
3.5 KiB
Markdown
44 lines
3.5 KiB
Markdown
# Проверка runtime OpenAPI
|
|
|
|
## Назначение
|
|
|
|
Проверка сравнивает OpenAPI, сформированный настроенным backend-приложением,
|
|
с описанием API, на котором основан frontend. Backend остаётся единственным
|
|
источником исполняемого HTTP-контракта; frontend-клиент является производным.
|
|
Причины выбора описаны в [ADR 002](../adr/002-nest-generated-openapi-contract.md).
|
|
|
|
Эта проверка подтверждает согласованность публичного контракта, но не заменяет
|
|
проверки каждого приложения и наблюдаемого HTTP-поведения.
|
|
|
|
## Выбор и направление изменения
|
|
|
|
Изменением контракта считается изменение маршрута, входного или выходного поля,
|
|
статуса либо формы ошибки. Внутреннее изменение представления без изменения
|
|
API не требует нового описания контракта.
|
|
|
|
Направление согласования: публичный API backend → OpenAPI → производное
|
|
описание и типизированный клиент frontend. Две независимо редактируемые версии
|
|
контракта создавали бы риск расхождения. Перед изменением, влияющим на
|
|
совместимость, учитываются существующие потребители и сохранность данных.
|
|
Семантика запросов и ошибок описана в [HTTP API](../architecture/http-api.md).
|
|
|
|
## Границы и результат
|
|
|
|
Сравнение выполняется на границе настроенного приложения, нормализует порядок
|
|
ключей JSON-объектов и сохраняет порядок массивов. Оно не обновляет сравниваемые
|
|
описания и клиент автоматически и не обращается к T-Bank или другим внешним
|
|
источникам. Несовпадение указывает на рассогласование контракта.
|
|
|
|
Равенство схем не доказывает фактическую работу валидации, авторизации,
|
|
статусов, cookie и обработки ошибок: для этого нужны наблюдения полного
|
|
HTTP-потока. Согласованность описаний и функциональная корректность —
|
|
разные доказательства.
|
|
|
|
## Граница e2e
|
|
|
|
`npm run test:openapi-contract` подготавливает отдельную временную SQLite-базу
|
|
через общий runner и выполняет только сравнение OpenAPI. Соседний frontend
|
|
checkout нужен для snapshot. Полные HTTP-сценарии запускает `test:e2e`;
|
|
миграция перед сравнением не подменяет проверку поведения приложения.
|
|
Подробности — в [сквозной проверке](verification.md#известное-ограничение-сквозной-проверки).
|