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) для новых опций
|