Generated API

Дата актуализации: 2026-06-22

Назначение

Проект использует Orval для генерации TypeScript API-клиентов и Zod-моделей из openapi.json. Generated-код не редактируется вручную.

Команда генерации

bun run apigen

Orval config находится в orval.config.ts.

Входной файл

openapi.json

В config есть нормализация русскоязычных тегов OpenAPI в стабильные англоязычные имена файлов:

Аутентификация -> authentication
Карта компетенций: аналитика -> competence-map-analytics
Мониторинг -> monitoring
Пользователь -> user
Управление пользователями -> user-management

Config также умеет читать первый валидный JSON-документ, если исходный OpenAPI-файл содержит лишние данные после первого JSON.

Выходные директории

src/shared/api/generated-api/
src/shared/model/generated-zod/

generated-api использует custom mutator:

src/shared/api/axiosInstance.ts

Это сохраняет единое поведение API-клиента: base URL, credentials, refresh flow, error handling и abort signal.

Public facade

Прикладной код не должен импортировать generated-файлы напрямую. Правильный путь:

import { getCompetenceMapAnalytics, type Login } from '@/shared/api'

Неправильный путь:

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.

3.2 KiB Raw Blame History Unescape Escape