api-codegen/AGENTS.md

API CodeGen - Описание проекта для AI агента

Назначение

CLI утилита для автоматической генерации TypeScript API клиента из OpenAPI/Swagger спецификации.

Архитектура

Основные компоненты

1. CLI (src/cli.ts) - точка входа, парсинг аргументов командной строки
2. Generator (src/generator.ts) - логика генерации кода через swagger-typescript-api
3. Config (src/config.ts) - валидация конфигурации
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 убирает суффикс "Controller" из имен методов:

• projectControllerUpdate → update
• authControllerLogin → login

Извлечение baseUrl

Хук onInit автоматически извлекает baseUrl из OpenAPI спецификации (servers[0].url)

Поддержка источников

• Локальные файлы: ./openapi.json
• URL: https://api.example.com/openapi.json

Использование

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 настроен с параметрами:

• httpClientType: 'fetch' - использование Fetch API
• unwrapResponseData: true - автоматическая распаковка данных ответа
• singleHttpClient: true - единый HTTP клиент
• extractRequestParams: true - извлечение параметров запросов
• extractRequestBody: true - извлечение тел запросов
• extractEnums: true - извлечение enum типов
• generateUnionEnums: true в split режиме - enum схемы генерируются как type union без runtime-кода

Примеры использования сгенерированного кода

import { createApiClient, HttpClient } from './generated';
import { getProfile } from './generated/operations/get-profile';
import { login } from './generated/operations/login';

const httpClient = new HttpClient();
httpClient.setSecurityData({ token: 'jwt-token' });

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
3. Конфигурация - можно расширить GeneratorConfig для новых опций