83 lines
3.2 KiB
Markdown
83 lines
3.2 KiB
Markdown
# Generated API
|
||
|
||
Дата актуализации: 2026-06-22
|
||
|
||
## Назначение
|
||
|
||
Проект использует Orval для генерации TypeScript API-клиентов и Zod-моделей из `openapi.json`.
|
||
Generated-код не редактируется вручную.
|
||
|
||
## Команда генерации
|
||
|
||
```bash
|
||
bun run apigen
|
||
```
|
||
|
||
Orval config находится в `orval.config.ts`.
|
||
|
||
## Входной файл
|
||
|
||
```text
|
||
openapi.json
|
||
```
|
||
|
||
В config есть нормализация русскоязычных тегов OpenAPI в стабильные англоязычные имена файлов:
|
||
|
||
- `Аутентификация` -> `authentication`
|
||
- `Карта компетенций: аналитика` -> `competence-map-analytics`
|
||
- `Мониторинг` -> `monitoring`
|
||
- `Пользователь` -> `user`
|
||
- `Управление пользователями` -> `user-management`
|
||
|
||
Config также умеет читать первый валидный JSON-документ, если исходный OpenAPI-файл содержит
|
||
лишние данные после первого JSON.
|
||
|
||
## Выходные директории
|
||
|
||
```text
|
||
src/shared/api/generated-api/
|
||
src/shared/model/generated-zod/
|
||
```
|
||
|
||
`generated-api` использует custom mutator:
|
||
|
||
```text
|
||
src/shared/api/axiosInstance.ts
|
||
```
|
||
|
||
Это сохраняет единое поведение API-клиента: base URL, credentials, refresh flow, error handling
|
||
и abort signal.
|
||
|
||
## Public facade
|
||
|
||
Прикладной код не должен импортировать generated-файлы напрямую. Правильный путь:
|
||
|
||
```ts
|
||
import { getCompetenceMapAnalytics, type Login } from '@/shared/api'
|
||
```
|
||
|
||
Неправильный путь:
|
||
|
||
```ts
|
||
import { api_v1_competence_map_analytics_list } from '@/shared/api/generated-api/competence-map-analytics'
|
||
```
|
||
|
||
Facade `src/shared/api/index.ts` сейчас экспортирует только используемые приложением endpoint
|
||
functions, token primitives, error helpers и DTO-типы.
|
||
|
||
## Правила изменений
|
||
|
||
- Не редактировать файлы в `generated-api` и `generated-zod` вручную.
|
||
- При изменении backend контракта обновить `openapi.json` и выполнить `bun run apigen`.
|
||
- После генерации выполнить `bun run check:full`.
|
||
- Если новому экрану нужен endpoint, сначала добавить осознанный export в `src/shared/api/index.ts`
|
||
или отдельный wrapper, а не импортировать generated-файл напрямую.
|
||
- Если DTO требует page-specific адаптации, mapper должен жить рядом с owner-страницей или рядом
|
||
с API wrapper, а не в generated-зоне.
|
||
|
||
## Tooling exclusions
|
||
|
||
Generated-директории исключены из Steiger и Prettier через `steiger.config.ts` и `.prettierignore`.
|
||
Это не разрешение писать ручной код внутри generated-зон. Исключение нужно только для стабильной
|
||
работы tooling после Orval generation.
|