Проверка 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 команды приложений.

Выбор и направление изменения

Определите, меняется wire contract (route, request/response field, status, error shape) или только внутренний код/UI model. Во втором случае snapshot не меняется.
Прочитайте HTTP semantics и нужный feature/domain source. Backend Nest controllers/DTO/Swagger metadata — единственный editable источник OpenAPI; specs repo не является вторым OpenAPI source.
Измените этот source и проверьте representative HTTP behavior. При изменении контракта скопируйте generated runtime OpenAPI в committed frontend snapshot, затем в frontend выполните npm run openapi:generate.
Выполните frontend npm run openapi:check и backend npm run test:openapi-contract, а также verify affected repos. Эти команды проверяют разное: schema parity не доказывает validation/auth/error behavior.

Generated frontend TS и backend Prisma client вручную не редактируются. Frontend domain/UI type допустим, когда он отличается от transport DTO по смыслу. Перед compatibility-sensitive изменением оцените существующих consumers и rollback/data constraints; одного обновления snapshot недостаточно.

Запуск

Из корня workspace:

cd backend
nvm use --silent
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.

3.6 KiB Raw Blame History Unescape Escape