# 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 вручную поверх сгенерированного клиента

```typescript
// Пример: типобезопасный хук
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