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

Назначение

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

Архитектура

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

CLI (src/cli.ts) - точка входа, парсинг аргументов командной строки
Generator (src/generator.ts) - логика генерации кода через swagger-typescript-api
Config (src/config.ts) - валидация конфигурации
Templates (src/templates/*.ejs) - EJS шаблоны для генерации кода

Технологический стек

Runtime: Bun
Языки: TypeScript
Зависимости:
- swagger-typescript-api - основной генератор
- commander - парсинг CLI аргументов
- ejs - шаблонизатор
- js-yaml - парсинг YAML
- chalk - цветной вывод в консоль

Рабочий процесс

Входные данные: OpenAPI спецификация (JSON/YAML файл или URL)
Обработка:
- Валидация конфигурации
- Чтение OpenAPI спецификации
- Применение кастомных шаблонов EJS
- Генерация TypeScript кода
Выходные данные: 3 файла в указанной директории:
- {FileName}.ts - API endpoints с методами
- http-client.ts - HTTP клиент с настройками
- data-contracts.ts - TypeScript типы

Ключевые особенности

Кастомизация имен методов

Хук 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 <имя-файла>]

Аргументы

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

httpClientType: 'fetch' - использование Fetch API
unwrapResponseData: true - автоматическая распаковка данных ответа
singleHttpClient: true - единый HTTP клиент
extractRequestParams: true - извлечение параметров запросов
extractRequestBody: true - извлечение тел запросов
extractEnums: true - извлечение enum типов

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

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 });

Точки расширения

Шаблоны - можно модифицировать EJS шаблоны в src/templates/
Хуки генератора - можно добавить новые хуки в hooks
Конфигурация - можно расширить GeneratorConfig для новых опций

4.7 KiB Raw Permalink Blame History Unescape Escape