api-codegen/AGENTS.md

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