Sergey Krylov
aac5b2f873
All checks were successful
- Create apps/docs/ with Docusaurus 3.7.0 - Add documentation: architecture, backend, frontend, infrastructure, development, ADR - Include 5 Mermaid diagrams (system architecture, request flow, modules, caching, deployment) - Configure as npm workspace with dev:docs/build:docs scripts - Copy existing ADR documents from docs/architecture/adr/
1.7 KiB
1.7 KiB
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 клиента (типобезопасные вызовы)
Процесс:
- Backend генерирует OpenAPI spec через
@nestjs/swagger openapi-typescriptна фронте генерирует типыopenapi-fetchсоздаёт типобезопасный HTTP-клиент- Разработчик пишет 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