API-контракты: OpenAPI, codegen и contract testing
↑ 5.4 Работа с API: REST, GraphQL, WebSocket · ← Предыдущая
Зачем это на собесе
Как фронт и бэк не расходятся в понимании API: схема как источник истины и автоматические проверки.
Объяснение
OpenAPI — машиночитаемое описание REST API (пути, параметры, схемы, ошибки). Источник истины: бэкенд генерирует спецификацию из кода (см. OpenAPI и Swagger, версионирование API) или команда пишет «schema-first».
Генерация клиента:
| Инструмент | Результат |
|---|---|
openapi-typescript | только типы (paths, components), лёгкий; с openapi-fetch — типизированный клиент |
| Orval | типы + хуки Vue Query/Axios + моки MSW |
@hey-api/openapi-ts | клиент и SDK |
| Kiota, NSwag | клиенты (в том числе для .NET) |
openapi-zod-client | Zod-схемы для runtime-валидации |
npx openapi-typescript https://api.example.com/openapi.json -o src/api/schema.d.tsimport createClient from "openapi-fetch";
import type { paths } from "./schema";
const client = createClient<paths>({ baseUrl: "/api" });
const { data, error } = await client.GET("/orders/{id}", { params: { path: { id: "42" } } }); // типы параметров и ответа выведеныContract testing — проверка соглашений без интеграционных стендов:
| Подход | Суть |
|---|---|
Проверка совместимости схемы (oasdiff breaking) | в CI бэкенда: изменения не ломают потребителей |
| Consumer-driven (Pact) | фронтенд описывает ожидания; бэкенд проверяет их в CI |
| Mock-сервер по схеме (Prism, MSW + схема) | фронтенд разрабатывается без бэкенда, ответы валидируются схемой |
| Валидация ответов на стенде (Schemathesis, Dredd) | автоматическое тестирование API по схеме (property-based) |
| Runtime-валидация на клиенте (Zod) | обнаружение расхождения в проде (с логированием) |
CI фронтенда: generate → git diff --exit-code (типы актуальны) → vue-tsc (компиляция ловит несовместимости после обновления схемы).
Процесс: изменение API → обновлённая схема в репозитории/артефакте → PR на фронт с регенерацией типов → совместимые изменения (добавление полей) деплоятся независимо, ломающие — по правилам версионирования (см. Версионирование и обратная совместимость).
Нюансы и подводные камни
- Схема не отражает семантику (бизнес-правила), только форму.
- Сгенерированный код не правят вручную; расширения — обёртками.
- Устаревшая схема хуже её отсутствия: автоматизируйте публикацию.
- Nullable/optional в разных генераторах трактуются по-разному — договоритесь.
- Большие спецификации замедляют генерацию: разбивайте по тегам.
Практика
- Сгенерируйте типы и клиент из OpenAPI и замените ручные типы.
- Добавьте проверку актуальности сгенерированного кода в CI.
- Настройте Prism/MSW для разработки без бэкенда.
Вопросы с ответами
Зачем OpenAPI фронтенду?
Единый контракт: типы и клиент генерируются автоматически, изменения API видны при компиляции.
Что такое contract testing?
Автоматическая проверка того, что потребитель и поставщик придерживаются согласованного контракта, без полного интеграционного стенда.