41 lines
1.7 KiB
Markdown
41 lines
1.7 KiB
Markdown
# 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
|