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