feat: автоматическое определение baseUrl, добавлена документация проекта

2025-10-28 09:18:08 +03:00
parent 15ed8c8b8d
commit 21c7ddfd54
4 changed files with 115 additions and 50 deletions
--- a/AI-PROJECT-OVERVIEW.md
+++ b/AI-PROJECT-OVERVIEW.md
@@ -0,0 +1,107 @@
+# 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) для новых опций