4.2 KiB
api-contract-generation Specification
Purpose
Определяет направление HTTP API contract между backend и frontend, исключающее ручное расхождение frontend snapshot и generated types.
Requirements
Requirement: Backend публикует машиночитаемый API-контракт
Backend SHALL публиковать версионированный OpenAPI-документ, описывающий доступные HTTP-маршруты, параметры, тела запросов, ответы и ошибки API /api/v1.
Scenario: Разработчик получает контракт API
- WHEN backend запущен в локальной среде разработки
- THEN разработчик может получить OpenAPI-документ для генерации frontend-клиента
Requirement: Frontend использует предоставленный OpenAPI snapshot
Frontend SHALL хранить в репозитории версионируемый snapshot предоставленного актуального OpenAPI-документа и генерировать transport types из этого snapshot. Команда генерации MUST читать frontend snapshot и обновлять сгенерированный результат. Она MUST NOT читать файлы соседнего backend checkout, запускать backend scripts или проверять backend runtime OpenAPI. Сгенерированный результат MUST храниться в frontend-репозитории.
Scenario: Types генерируются из предоставленного snapshot
- WHEN разработчик запускает frontend-команду генерации
- THEN frontend обновляет generated transport types из versioned snapshot
Scenario: API-контракт изменяется
- WHEN backend меняет опубликованный API-контракт и frontend получает новый snapshot
- THEN frontend может повторно сгенерировать transport types до интеграции изменения
Requirement: Frontend не зависит от OpenAPI во время работы
Работающий frontend MUST использовать ранее сгенерированные transport types и MUST NOT требовать доступность Swagger или OpenAPI endpoint во время запуска, выполнения пользовательского сценария, генерации types или локальной проверки актуальности generated artifact.
Scenario: OpenAPI endpoint недоступен после сборки frontend
- WHEN frontend уже собран, а endpoint OpenAPI временно недоступен
- THEN frontend продолжает использовать сгенерированный код для запросов к API
Scenario: Локальная проверка выполняется без backend
- WHEN разработчик запускает локальный frontend quality gate
- THEN проверка актуальности generated artifact использует сохранённый snapshot и не обращается к OpenAPI endpoint
Requirement: Frontend обнаруживает дрейф сгенерированного контракта
Frontend SHALL проверять, что committed generated transport types соответствуют versioned OpenAPI snapshot, и MUST завершать quality gate с ошибкой при расхождении.
Scenario: Generated artifact устарел
- WHEN OpenAPI snapshot изменён, а generated transport types не обновлены
- THEN проверка контракта завершается с ошибкой
Scenario: Generated artifact изменён вручную
- WHEN generated transport types отличаются от результата генерации из сохранённого snapshot
- THEN проверка контракта завершается с ошибкой