docs/development/runtime-openapi-verification.md

Проверка runtime OpenAPI

Назначение

npm run test:openapi-contract в backend/ строит configured Nest application, создаёт runtime OpenAPI document и сверяет его с committed snapshot frontend/src/shared/api/spec/openapi.json после детерминированной canonicalization.

Это отдельный контрактный gate, а не общий verifier всех репозиториев. Он нужен перед изменениями backend API или frontend transport contract и не заменяет локальные lint/typecheck команды приложений.

Запуск

Из корня workspace:

cd backend
npm run test:openapi-contract

Перед первым запуском в backend выполняют npm ci под Node 22.

Границы и результат

Команда:

• использует configured Nest application на integration boundary;
• рекурсивно сортирует только ключи JSON objects и сохраняет порядок arrays;
• не записывает snapshot или generated frontend types.

Она не записывает committed snapshot или generated frontend types и не обращается к T-Bank либо другому внешнему сервису. Если контракт действительно изменён, snapshot обновляют явным копированием backend OpenAPI document в frontend/src/shared/api/spec/openapi.json, затем в frontend запускают npm run openapi:generate и снова выполняют эту проверку.

Ограничение e2e

Проверка Swagger не запускает backend e2e tests. WL-P2-05 (runnable e2e) и WL-P2-13 (единый workspace verdict) отложены из-за нестабильного Prisma 7.9.1 migration gate; дата, rationale и trigger пересмотра находятся в audit remediation registry.