moex-vibe/docs/architecture/adr/ADR-005-openapi-codegen-frontend.md

ADR-005: OpenAPI Codegen with openapi-typescript

Status: Accepted
Date: 2026-06-13
Deciders: Architect, Tech Lead

Context

Frontend должен потреблять API бэкенда. Ручное написание клиентов и DTO приводит к рассинхронизации с бэкендом и ошибкам типизации.

Decision

Использовать openapi-typescript + openapi-fetch для генерации:

• TypeScript типов (DTO, request/response schemas)
• Fetcher клиента (типобезопасные вызовы)

Процесс:

1. Backend генерирует OpenAPI spec через @nestjs/swagger
2. openapi-typescript на фронте генерирует типы
3. openapi-fetch создаёт типобезопасный HTTP-клиент
4. Разработчик пишет TanStack Query hooks вручную поверх сгенерированного клиента

// Пример: типобезопасный хук
import { getSharesSecid } from '@/api/client';
import type { components } from '@/api/types';

export function useStock(secid: string) {
  return useQuery({
    queryKey: ['stock', secid],
    queryFn: () => getSharesSecid(secid),
    staleTime: 900_000, // 15 min
  });
}

Consequences

• Полная типобезопасность на стыке frontend/backend
• Автоматическая синхронизация с API-контрактом
• TanStack Query hooks пишутся вручную — полный контроль staleTime/caching
• Добавляется шаг в CI: codegen при изменении OpenAPI spec