S.Gromov
4ce5ea9b65
- ошибки парсинга успешных ответов проброшены в onError - добавлена защита от перезаписи явного Authorization - обновлены тесты, README и примеры кастомизации
141 lines
5.8 KiB
Markdown
141 lines
5.8 KiB
Markdown
# API CodeGen - Описание проекта для AI агента
|
||
|
||
## Назначение
|
||
CLI утилита для автоматической генерации TypeScript API клиента из OpenAPI/Swagger спецификации.
|
||
|
||
## Архитектура
|
||
|
||
### Основные компоненты
|
||
1. **CLI** ([`src/cli.ts`](src/cli.ts:1)) - точка входа, парсинг аргументов командной строки
|
||
2. **Generator** ([`src/generator.ts`](src/generator.ts:1)) - логика генерации кода через swagger-typescript-api
|
||
3. **Config** ([`src/config.ts`](src/config.ts:1)) - валидация конфигурации
|
||
4. **Templates** (`src/templates/*.ejs`) - EJS шаблоны для генерации кода
|
||
|
||
### Технологический стек
|
||
- **Runtime**: Bun
|
||
- **Языки**: TypeScript
|
||
- **Зависимости**:
|
||
- `swagger-typescript-api` - основной генератор
|
||
- `commander` - парсинг CLI аргументов
|
||
- `ejs` - шаблонизатор
|
||
- `js-yaml` - парсинг YAML
|
||
- `chalk` - цветной вывод в консоль
|
||
|
||
## Рабочий процесс
|
||
|
||
1. **Входные данные**: OpenAPI спецификация (JSON/YAML файл или URL)
|
||
2. **Обработка**:
|
||
- Валидация конфигурации
|
||
- Чтение OpenAPI спецификации
|
||
- Применение кастомных шаблонов EJS
|
||
- Генерация TypeScript кода
|
||
3. **Выходные данные по умолчанию**: legacy монолитный файл `{FileName}.ts`
|
||
4. **Выходные данные в `split` режиме**: tree-shaking friendly структура:
|
||
- `http-client.ts` - HTTP клиент с настройками
|
||
- `data-contracts.ts` - TypeScript типы
|
||
- `create-api-client.ts` - helper для привязки выбранного графа методов к клиенту
|
||
- `operations/*.ts` - один endpoint на файл
|
||
- `index.ts` - barrel exports
|
||
|
||
## Ключевые особенности
|
||
|
||
### Кастомизация имен методов
|
||
Хук [`onFormatRouteName`](src/generator.ts:76) убирает суффикс "Controller" из имен методов:
|
||
- `projectControllerUpdate` → `update`
|
||
- `authControllerLogin` → `login`
|
||
|
||
### Извлечение baseUrl
|
||
Хук [`onInit`](src/generator.ts:91) автоматически извлекает baseUrl из OpenAPI спецификации (`servers[0].url`)
|
||
|
||
### Поддержка источников
|
||
- Локальные файлы: `./openapi.json`
|
||
- URL: `https://api.example.com/openapi.json`
|
||
|
||
## Использование
|
||
|
||
```bash
|
||
api-codegen -i <путь-к-openapi> -o <выходная-директория> [-n <имя-файла>] [--mode single|split|both]
|
||
```
|
||
|
||
### Аргументы
|
||
- `-i, --input` - путь к OpenAPI файлу (локальный или URL)
|
||
- `-o, --output` - директория для сохранения
|
||
- `-n, --name` - имя монолитного файла без `.ts`
|
||
- `--mode` - режим генерации: `single` (по умолчанию), `split`, `both`
|
||
- `--single-file` - устаревший алиас для `--mode single`
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
src/
|
||
├── cli.ts # CLI интерфейс
|
||
├── config.ts # Типы и валидация конфигурации
|
||
├── generator.ts # Основная логика генерации
|
||
├── templates/ # EJS шаблоны
|
||
│ ├── api.ejs
|
||
│ ├── operation.ejs
|
||
│ ├── create-api-client.ejs
|
||
│ ├── http-client.ejs
|
||
│ ├── data-contracts.ejs
|
||
│ └── ...
|
||
└── utils/
|
||
└── file.ts # Утилиты для работы с файлами
|
||
```
|
||
|
||
## Конфигурация генератора
|
||
|
||
[`swaggerGenerateApi`](src/generator.ts:38) настроен с параметрами:
|
||
- `httpClientType: 'fetch'` - использование Fetch API
|
||
- `unwrapResponseData: true` - автоматическая распаковка данных ответа
|
||
- `singleHttpClient: true` - единый HTTP клиент
|
||
- `extractRequestParams: true` - извлечение параметров запросов
|
||
- `extractRequestBody: true` - извлечение тел запросов
|
||
- `extractEnums: true` - извлечение enum типов
|
||
- `generateUnionEnums: true` в `split` режиме - enum схемы генерируются как type union без runtime-кода
|
||
|
||
## Примеры использования сгенерированного кода
|
||
|
||
```typescript
|
||
import { createApiClient, HttpClient } from './generated';
|
||
import { getProfile } from './generated/operations/get-profile';
|
||
import { login } from './generated/operations/login';
|
||
|
||
const token = 'jwt-token';
|
||
|
||
const httpClient = new HttpClient({
|
||
onRequest: (params) => {
|
||
if (!params.secure) {
|
||
return params;
|
||
}
|
||
|
||
const headers = new Headers(params.headers);
|
||
|
||
if (!headers.has('Authorization')) {
|
||
headers.set('Authorization', `Bearer ${token}`);
|
||
}
|
||
|
||
return {
|
||
...params,
|
||
headers,
|
||
};
|
||
},
|
||
});
|
||
|
||
const api = createApiClient(httpClient, {
|
||
auth: {
|
||
getProfile,
|
||
login,
|
||
},
|
||
});
|
||
|
||
// Вызов API методов
|
||
const user = await api.auth.getProfile();
|
||
const result = await api.auth.login({ email, password });
|
||
```
|
||
|
||
## Точки расширения
|
||
|
||
1. **Шаблоны** - можно модифицировать EJS шаблоны в `src/templates/`
|
||
2. **Хуки генератора** - можно добавить новые хуки в [`hooks`](src/generator.ts:75)
|
||
3. **Конфигурация** - можно расширить [`GeneratorConfig`](src/config.ts:4) для новых опций
|