47 lines
3.4 KiB
Markdown
47 lines
3.4 KiB
Markdown
# OpenAPI contract flow
|
|
|
|
## Назначение
|
|
|
|
Backend остаётся источником HTTP-контракта и формирует OpenAPI из публичного
|
|
API. Frontend принимает предоставленный `openapi.json` как актуальный вход,
|
|
хранит его snapshot и генерирует из него transport types локально. Причины
|
|
выбора backend-generated контракта описаны в
|
|
[ADR 002](../adr/002-nest-generated-openapi-contract.md), отказ от frontend
|
|
проверки backend runtime-схемы — в [ADR 014](../adr/014-trusted-openapi-input.md).
|
|
|
|
Frontend не проверяет, что переданный snapshot совпадает с текущим backend
|
|
runtime OpenAPI, не фиксирует пару frontend/backend SHA и не зависит от пути к
|
|
соседнему backend checkout. Подготовка и доставка актуального OpenAPI-документа
|
|
находятся вне frontend.
|
|
|
|
## Выбор и направление изменения
|
|
|
|
Изменением контракта считается изменение маршрута, входного или выходного поля,
|
|
статуса либо формы ошибки. Внутреннее изменение представления без изменения
|
|
API не требует нового описания контракта.
|
|
|
|
Направление согласования: публичный API backend → предоставленный OpenAPI →
|
|
frontend snapshot → generated types. Две независимо редактируемые версии
|
|
контракта создавали бы риск расхождения. Перед изменением, влияющим на
|
|
совместимость, учитываются существующие потребители и сохранность данных.
|
|
Семантика запросов и ошибок описана в [HTTP API](../architecture/http-api.md).
|
|
|
|
## Границы и результат
|
|
|
|
Frontend-команда генерации читает только committed snapshot и обновляет
|
|
generated types. Frontend-проверка генерирует types из этого snapshot во
|
|
временный каталог и сравнивает результат с committed generated artifact.
|
|
Несовпадение означает, что snapshot и generated types в frontend расходятся.
|
|
|
|
Эта проверка не доказывает актуальность snapshot относительно backend. Это
|
|
принятое допущение, а не свойство frontend gate. Она также не доказывает
|
|
фактическую работу валидации, авторизации, статусов, cookie и обработки ошибок:
|
|
для этого нужны наблюдения полного HTTP-потока.
|
|
|
|
## Граница runtime
|
|
|
|
Работающий frontend использует сгенерированные types и обычные HTTP-запросы к
|
|
API. Swagger или OpenAPI endpoint не являются runtime-зависимостью SPA.
|
|
Полные HTTP-сценарии и хранение данных проверяются отдельными backend-gates;
|
|
локальный frontend gate выполняется без backend.
|