api-contract-generation Specification

Purpose

Определяет единый, проверяемый контракт HTTP API между backend и frontend, исключающий ручное расхождение типов и маршрутов.

Requirements

Requirement: Backend публикует машиночитаемый API-контракт

Backend SHALL публиковать версионированный OpenAPI-документ, описывающий доступные HTTP-маршруты, параметры, тела запросов, ответы и ошибки API /api/v1.

Scenario: Разработчик получает контракт API

WHEN backend запущен в локальной среде разработки
THEN разработчик может получить OpenAPI-документ для генерации frontend-клиента

Requirement: Frontend использует сгенерированный API-клиент

Frontend SHALL хранить в репозитории версионируемый snapshot опубликованного OpenAPI-документа и генерировать transport types из этого snapshot. Команда синхронизации MUST получать документ из backend, а затем обновлять snapshot и сгенерированный результат только при успешном завершении всего процесса. Сгенерированный результат MUST храниться в frontend-репозитории.

Scenario: API-контракт синхронизируется

WHEN разработчик запускает команду синхронизации при доступном backend с валидным OpenAPI-документом
THEN frontend обновляет versioned snapshot и сгенерированные transport types из опубликованного контракта

Scenario: API-контракт изменяется

WHEN backend меняет опубликованный API-контракт
THEN frontend может синхронизировать snapshot и повторно сгенерировать transport types до интеграции изменения

Scenario: Синхронизация контракта завершается ошибкой

WHEN backend недоступен или публикует невалидный OpenAPI-документ
THEN команда завершается с ошибкой и существующие snapshot и сгенерированные transport types не изменяются

Requirement: Frontend не зависит от OpenAPI во время работы

Работающий frontend MUST использовать ранее сгенерированные transport types и MUST NOT требовать доступность Swagger или OpenAPI endpoint во время запуска, выполнения пользовательского сценария или локальной проверки актуальности generated artifact. Доступ к backend OpenAPI endpoint разрешён только команде синхронизации snapshot.

Scenario: OpenAPI endpoint недоступен после сборки frontend

WHEN frontend уже собран, а endpoint OpenAPI временно недоступен
THEN frontend продолжает использовать сгенерированный код для запросов к API

Scenario: Локальная проверка выполняется без backend

WHEN разработчик запускает локальный quality gate без доступного backend
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 проверка контракта завершается с ошибкой

4.8 KiB Raw Blame History Unescape Escape