107 lines
4.7 KiB
Markdown
107 lines
4.7 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. **Выходные данные**: 3 файла в указанной директории:
|
||
- `{FileName}.ts` - API endpoints с методами
|
||
- `http-client.ts` - HTTP клиент с настройками
|
||
- `data-contracts.ts` - TypeScript типы
|
||
|
||
## Ключевые особенности
|
||
|
||
### Кастомизация имен методов
|
||
Хук [`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 <имя-файла>]
|
||
```
|
||
|
||
### Аргументы
|
||
- `-i, --input` - путь к OpenAPI файлу (локальный или URL)
|
||
- `-o, --output` - директория для сохранения
|
||
- `-n, --name` - опциональное имя файла (по умолчанию из `spec.info.title`)
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
src/
|
||
├── cli.ts # CLI интерфейс
|
||
├── config.ts # Типы и валидация конфигурации
|
||
├── generator.ts # Основная логика генерации
|
||
├── templates/ # EJS шаблоны
|
||
│ ├── api.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 типов
|
||
|
||
## Примеры использования сгенерированного кода
|
||
|
||
```typescript
|
||
import { Api, HttpClient } from './Api';
|
||
|
||
const httpClient = new HttpClient();
|
||
httpClient.setSecurityData({ token: 'jwt-token' });
|
||
|
||
const api = new Api(httpClient);
|
||
|
||
// Вызов 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) для новых опций |