3.4 KiB
OpenAPI contract flow
Назначение
Backend остаётся источником HTTP-контракта и формирует OpenAPI из публичного
API. Frontend принимает предоставленный openapi.json как актуальный вход,
хранит его snapshot и генерирует из него transport types локально. Причины
выбора backend-generated контракта описаны в
ADR 002, отказ от frontend
проверки backend runtime-схемы — в ADR 014.
Frontend не проверяет, что переданный snapshot совпадает с текущим backend runtime OpenAPI, не фиксирует пару frontend/backend SHA и не зависит от пути к соседнему backend checkout. Подготовка и доставка актуального OpenAPI-документа находятся вне frontend.
Выбор и направление изменения
Изменением контракта считается изменение маршрута, входного или выходного поля, статуса либо формы ошибки. Внутреннее изменение представления без изменения API не требует нового описания контракта.
Направление согласования: публичный API backend → предоставленный OpenAPI → frontend snapshot → generated types. Две независимо редактируемые версии контракта создавали бы риск расхождения. Перед изменением, влияющим на совместимость, учитываются существующие потребители и сохранность данных. Семантика запросов и ошибок описана в HTTP API.
Границы и результат
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.