ts-openapi-codegen 2.1.0-beta.1 → 2.1.0-beta.10

package/README.rus.md

@@ -14,7 +14,6 @@
 ![lines-image]
 ![Minimum node.js version](https://badgen.net/npm/node/next)
 
-
 > Node.js библиотека, которая генерирует клиенты Typescript на основе спецификации OpenAPI.
 
 ## Почему?
@@ -28,953 +27,47 @@
 - Поддерживает tsc и @babel/plugin-transform-typescript
 - Поддерживает кастомизацию имен моделей
 - Поддерживает внешние ссылки с помощью [`swagger-parser`](https://github.com/APIDevTools/swagger-parser/)
+- Поддерживает strict-диагностику OpenAPI с JSON-отчетом (`--strict-openapi`, `--report-file`)
+- Поддерживает плагины генератора (`plugins`), включая встроенный `x-typescript-type`
 - Поддерживает генерацию бинарных request/response (`format: binary` -> `Blob`)
+- Поддерживает opt-in кэш генерации и инкрементальную запись (`--cache`, `--cachePath`, `--cacheStrategy`, `--cacheDebug`)
+- Сгенерированные сервисы принимают `RequestExecutor` в конструкторе (`request` / `requestRaw`, interceptors, `customExecutorPath` / `createExecutorAdapter`, `createLegacyRequestAdapter`)
+- CLI `init --requestFormat` создаёт scaffold кастомного HTTP-слоя: legacy transport, `createExecutorAdapter` или автономный `RequestExecutor`
+- `check-config` проверяет наличие файлов `request` / `customExecutorPath` и экспорт `createExecutorAdapter`
+- Опциональное форматирование вывода через `prettierConfigPath` (явный путь к конфигу Prettier)
+- Опциональный пакетный ESLint `--fix` после генерации при указании `tsconfigPath` и `eslintConfigPath`
+- Поддерживает унифицированный отчёт `analyze-diff` (`schemaVersion: 2.0.0`) с отдельными секциями `semantic` (CI/governance) и `structural` (генерация)
+- Восстанавливает совместимость `generate --useHistory` с semantic diff-отчётами (ghost operations/properties, coercion, rename miracles)
+- Использует селективное раскрытие OpenAPI `$ref` в analyze-diff для более быстрого и безопасного сравнения
+- Автоматическое обнаружение RENAME / TYPE_COERCION miracles из semantic-изменений свойств
 
 ## Установка
 
-```
-npm install ts-openapi-codegen --save-dev
-```
-
-## Использование
-
-CLI инструмент поддерживает шесть команд: `generate`, `check-config`, `update-config`, `init`, `preview-changes` и `analyze-diff`.
-
-### Команда: `generate`
-
-Генерирует TypeScript клиент на основе спецификаций OpenAPI.
-
-**Базовое использование:**
-```bash
-openapi generate --input ./spec.json --output ./dist
-```
-
-**Все доступные опции:**
-
-| Опция | Короткая | Тип | По умолчанию | Описание |
-|-------|----------|-----|--------------|----------|
-| `--input` | `-i` | string | - | Спецификация OpenAPI (путь, URL или строковое содержимое) - **обязательно** |
-| `--output` | `-o` | string | - | Выходная директория - **обязательно** |
-| `--openapi-config` | `-ocn` | string | `openapi.config.json` | Путь к файлу конфигурации |
-| `--outputCore` | `-oc` | string | `{output}` | Выходная директория для core файлов |
-| `--outputServices` | `-os` | string | `{output}` | Выходная директория для сервисов |
-| `--outputModels` | `-om` | string | `{output}` | Выходная директория для моделей |
-| `--outputSchemas` | `-osm` | string | `{output}` | Выходная директория для схем |
-| `--httpClient` | `-c` | string | `fetch` | HTTP клиент для генерации: `fetch`, `xhr`, `node`, или `axios` |
-| `--useOptions` | - | boolean | `false` | Использовать опции вместо аргументов |
-| `--useUnionTypes` | - | boolean | `false` | Использовать union типы вместо enums |
-| `--excludeCoreServiceFiles` | - | boolean | `false` | Исключить генерацию core и сервисных файлов |
-| `--request` | - | string | - | Путь к пользовательскому файлу запросов |
-| `--customExecutorPath` | - | string | - | Путь к пользовательскому модулю `createExecutorAdapter` |
-| `--interfacePrefix` | - | string | `I` | Префикс для интерфейсов моделей |
-| `--enumPrefix` | - | string | `E` | Префикс для enum моделей |
-| `--typePrefix` | - | string | `T` | Префикс для type моделей |
-| `--useCancelableRequest` | - | boolean | `false` | Использовать отменяемый promise как тип возврата |
-| `--sortByRequired` | `-s` | boolean | `false` | Использовать расширенную стратегию сортировки для аргументов функций |
-| `--useSeparatedIndexes` | - | boolean | `false` | Использовать отдельные index файлы для core, models, schemas и services |
-| `--logLevel` | `-l` | string | `error` | Уровень логирования: `info`, `warn`, или `error` |
-| `--logTarget` | `-t` | string | `console` | Цель логирования: `console` или `file` |
-| `--validationLibrary` | - | string | `none` | Библиотека валидации для генерации схем: `none`, `zod`, `joi`, `yup`, или `jsonschema` |
-| `--emptySchemaStrategy` | - | string | `keep` | Стратегия для пустых схем: `keep`, `semantic`, или `skip` |
-| `--modelsMode` | - | string | `interfaces` | Режим генерации моделей: `interfaces` или `classes` |
-| `--useHistory` | - | boolean | `false` | Применять diff-отчёт при генерации |
-| `--diffReport` | - | string | `./openapi-diff-report.json` | Путь к diff-отчёту |
-
-**Примеры:**
-```bash
-# Базовая генерация
-openapi generate --input ./spec.json --output ./dist
-
-# С пользовательским HTTP клиентом
-openapi generate --input ./spec.json --output ./dist --httpClient axios
-
-# С файлом конфигурации
-openapi generate --openapi-config ./my-config.json
-
-# Со всеми опциями через CLI
-openapi generate \
-  --input ./spec.json \
-  --output ./dist \
-  --httpClient fetch \
-  --useOptions \
-  --useUnionTypes \
-  --logLevel info
-```
-
-### Команда: `check-config`
-
-Проверяет структуру и значения файла конфигурации.
-
-**Использование:**
-```bash
-openapi check-config
-openapi check-config --openapi-config ./custom-config.json
-```
-
-**Опции:**
-- `--openapi-config` / `-ocn` - Путь к файлу конфигурации (по умолчанию: `openapi.config.json`)
-
-### Команда: `update-config`
-
-Обновляет файл конфигурации до последней поддерживаемой версии схемы.
-
-**Использование:**
-```bash
-openapi update-config
-openapi update-config --openapi-config ./custom-config.json
-```
-
-**Опции:**
-- `--openapi-config` / `-ocn` - Путь к файлу конфигурации (по умолчанию: `openapi.config.json`)
-
-### Команда: `init`
-
-Генерирует шаблон файла конфигурации.
-
-**Использование:**
 ```bash
-# Генерация шаблона с настройками по умолчанию
-openapi init
-
-# Пользовательское имя файла конфигурации
-openapi init --openapi-config ./my-config.json
-
-# Явно указать директорию со спецификациями OpenAPI
-openapi init --specs-dir ./openapi
-```
-
-**Опции:**
-- `--openapi-config` / `-ocn` - Путь к выходному файлу конфигурации (по умолчанию: `openapi.config.json`)
-- `--specs-dir` / `-sd` - Директория с файлами OpenAPI спецификаций (по умолчанию: `./openapi`)
-- `--request` - Путь к пользовательскому request-файлу
-- `--useCancelableRequest` - Включить генерацию cancelable request
-- `--useInteractiveMode` - Включить интерактивный режим настройки
-
-### Команда: `preview-changes`
-
-Показывает различия между уже сгенерированным кодом и новым результатом генерации без перезаписи текущей директории generated-кода.
-
-**Использование:**
-```bash
-openapi preview-changes
-openapi preview-changes --openapi-config ./custom-config.json
-```
-
-**Опции:**
-- `--openapi-config` / `-ocn` - Путь к файлу конфигурации (по умолчанию: `openapi.config.json`)
-- `--generated-dir` / `-gd` - Директория с текущим generated-кодом (по умолчанию: `./generated`)
-- `--preview-dir` / `-pd` - Временная директория для preview-генерации (по умолчанию: `./.ts-openapi-codegen-preview-changes`)
-- `--diff-dir` / `-dd` - Директория для diff-отчетов (по умолчанию: `./.ts-openapi-codegen-diff-changes`)
-
-### Команда: `analyze-diff`
-
-Анализирует изменения между двумя версиями OpenAPI и формирует JSON‑отчет.
-
-**Использование:**
-```bash
-openapi analyze-diff --input ./openapi/current.yaml --compare-with ./openapi/previous.yaml --output-report ./openapi-diff-report.json
-openapi analyze-diff --input ./openapi/spec.yaml --git HEAD~1
-```
-
-**Опции:**
-- `--input` / `-i` - Путь к текущей спецификации OpenAPI (обязательно)
-- `--compare-with` - Путь к предыдущей спецификации
-- `--git` - Git ref для чтения предыдущей версии спецификации (например, `HEAD~1`)
-- `--output-report` - Путь для сохранения diff‑отчёта (по умолчанию: `./openapi-diff-report.json`)
-
-#### Miracles и подтверждение
-
-В diff‑отчёте может быть раздел `miracles` с обнаруженными переименованиями/коэрсингом типов. В генерации применяются только подтверждённые записи.
-
-**Как подтверждать чудеса:**
-1. Запустите `analyze-diff` и откройте отчёт (по умолчанию: `./openapi-diff-report.json`).
-2. Найдите нужную запись в `miracles`.
-3. Измените `"status": "auto-generated"` на `"status": "confirmed"` и закоммитьте отчёт.
-
-Пример (фрагмент):
-```json
-{
-  "miracles": [
-    {
-      "oldPath": "$.components.schemas.User.properties.user_name",
-      "newPath": "$.components.schemas.User.properties.userName",
-      "type": "RENAME",
-      "confidence": 0.85,
-      "status": "confirmed"
-    }
-  ]
-}
-```
-
-### Файл конфигурации
-
-Вместо передачи всех опций через CLI, вы можете использовать файл конфигурации. Создайте `openapi.config.json` в корне вашего проекта:
-
-**Формат с одним набором опций:**
-```json
-{
-    "input": "./spec.json",
-    "output": "./dist",
-    "client": "fetch",
-    "useOptions": false,
-    "useUnionTypes": false,
-    "excludeCoreServiceFiles": false,
-    "interfacePrefix": "I",
-    "enumPrefix": "E",
-    "typePrefix": "T",
-    "useCancelableRequest": false,
-    "sortByRequired": false,
-    "useSeparatedIndexes": false,
-    "request": "./custom-request.ts",
-    "customExecutorPath": "./custom/createExecutorAdapter.ts",
-    "modelsMode": "interfaces",
-    "useHistory": false,
-    "diffReport": "./openapi-diff-report.json",
-    "models": {
-        "mode": "interfaces"
-    },
-    "analyze": {
-        "useHistory": false,
-        "reportPath": "./openapi-diff-report.json"
-    },
-    "miracles": {
-        "enabled": true,
-        "confidence": 1,
-        "types": ["RENAME", "TYPE_COERCION"]
-    }
-}
-```
-
-**Формат с несколькими наборами опций (с общим блоком):**
-```json
-{
-    "output": "./dist",
-    "client": "fetch",
-    "excludeCoreServiceFiles": true,
-    "items": [
-        {
-            "input": "./first.yml"
-        },
-        {
-            "input": "./second.yml",
-            "output": "./dist-v2"
-        }
-    ]
-}
-```
-
-**Формат массива (несколько конфигураций):**
-```json
-[
-    {
-        "input": "./first.yml",
-        "output": "./dist",
-        "client": "xhr"
-    },
-    {
-        "input": "./second.yml",
-        "output": "./dist",
-        "client": "fetch"
-    }
-]
-```
-
-| Имя | Тип | По умолчанию | Описание |
-|-----|-----|--------------|----------|
-| `input` | string | - | Путь/URL спецификации OpenAPI (обязательно для items) |
-| `output` | string | - | Выходная директория (обязательно) |
-| `outputCore` | string | `{output}` | Выходная директория для core файлов |
-| `outputServices` | string | `{output}` | Выходная директория для сервисов |
-| `outputModels` | string | `{output}` | Выходная директория для моделей |
-| `outputSchemas` | string | `{output}` | Выходная директория для схем |
-| `client` | string | `fetch` | HTTP клиент: `fetch`, `xhr`, `node`, или `axios` |
-| `useOptions` | boolean | `false` | Использовать опции вместо аргументов |
-| `useUnionTypes` | boolean | `false` | Использовать union типы вместо enums |
-| `excludeCoreServiceFiles` | boolean | `false` | Исключить генерацию core и сервисных файлов |
-| `request` | string | - | Путь к пользовательскому файлу запросов |
-| `customExecutorPath` | string | - | Путь к пользовательскому модулю `createExecutorAdapter` |
-| `interfacePrefix` | string | `I` | Префикс для интерфейсов моделей |
-| `enumPrefix` | string | `E` | Префикс для enum моделей |
-| `typePrefix` | string | `T` | Префикс для type моделей |
-| `useCancelableRequest` | boolean | `false` | Использовать отменяемый promise как тип возврата |
-| `sortByRequired` | boolean | `false` | Расширенная стратегия сортировки для аргументов |
-| `useSeparatedIndexes` | boolean | `false` | Использовать отдельные index файлы |
-| `items` | array | - | Массив конфигураций (для формата multi-options) |
-| `validationLibrary` | string | `none` | Библиотека валидации для генерации схем: `none`, `zod`, `joi`, `yup`, или `jsonschema` |
-| `emptySchemaStrategy` | string | `keep` | Стратегия для пустых схем: `keep`, `semantic`, или `skip` |
-| `modelsMode` | string | `interfaces` | Режим генерации моделей: `interfaces` или `classes` |
-| `useHistory` | boolean | `false` | Применять diff‑отчёт при генерации |
-| `diffReport` | string | `./openapi-diff-report.json` | Путь к diff‑отчёту |
-| `models` | object | - | Секция конфигурации моделей (например, `mode`) |
-| `analyze` | object | - | Секция анализа (например, reportPath, useHistory, ignore) |
-| `miracles` | object | - | Секция чудес (enabled, confidence, types) |
-
-**Примечание:** Вы можете использовать команду `init` для генерации шаблона файла конфигурации.
-
-## Примеры
-
-### Использование CLI команд
-
-**Базовая генерация:**
-```bash
-openapi generate --input ./spec.json --output ./dist
-```
-
-**С файлом конфигурации:**
-```bash
-# Сначала создайте файл конфигурации
-openapi init
-
-# Затем выполните генерацию
-openapi generate
-```
-
-**С DTO моделями (режим classes):**
-```bash
-openapi generate --input ./spec.json --output ./dist --modelsMode classes
-```
-
-**Сгенерировать diff‑отчёт:**
-```bash
-openapi analyze-diff --input ./openapi/current.yaml --compare-with ./openapi/previous.yaml --output-report ./openapi-diff-report.json
-```
-
-**Проверка конфигурации:**
-```bash
-openapi check-config
-openapi update-config
+npm install ts-openapi-codegen --save-dev
 ```
 
-**Предпросмотр изменений перед применением:**
-```bash
-openapi preview-changes
-```
+## Agent Skills
 
-### Использование NPX
+Для AI-агентов в пакете есть [Agent Skills](https://agentskills.io) по RequestExecutor и Marauder. После установки:
 
 ```bash
-npx ts-openapi-codegen generate --input ./spec.json --output ./dist
-```
-
-### Использование скриптов в package.json
-
-**package.json**
-```json
-{
-    "scripts": {
-        "generate": "openapi generate --input ./spec.json --output ./dist",
-        "generate:config": "openapi generate",
-        "check-config": "openapi check-config",
-        "update-config": "openapi update-config",
-        "init-config": "openapi init",
-        "preview-changes": "openapi preview-changes"
-    }
-}
-```
-
-### Node.js API
-
-```javascript
-const OpenAPI = require('ts-openapi-codegen');
-
-OpenAPI.generate({
-    input: './spec.json',
-    output: './dist'
-});
-
-// Или передав содержимое спецификации напрямую 🚀
-OpenAPI.generate({
-    input: require('./spec.json'),
-    output: './dist'
-});
-```
-
-
-## Возможности
-
-### HTTP Клиенты
-
-Генератор поддерживает несколько HTTP клиентов:
-- **fetch** (по умолчанию) - Browser Fetch API
-- **xhr** - XMLHttpRequest
-- **node** - Node.js совместимый клиент, использующий `node-fetch`
-- **axios** - Axios HTTP клиент
-
-Выберите клиент используя опцию `--httpClient` или свойство `client` в файле конфигурации.
-
-### Стиль аргументов vs. Стиль объектов `--useOptions`
-В JavaScript или TypeScript нет [именованных параметров](https://en.wikipedia.org/wiki/Named_parameter), поэтому
-мы предлагаем флаг `--useOptions` для генерации кода в двух разных стилях.
-
-**Стиль аргументов:**
-```typescript
-function createUser(name: string, password: string, type?: string, address?: string) {
-    // ...
-}
-
-// Использование
-createUser('Jack', '123456', undefined, 'NY US');
-```
-
-**Стиль объектов:**
-```typescript
-function createUser({ name, password, type, address }: {
-    name: string,
-    password: string,
-    type?: string
-    address?: string
-}) {
-    // ...
-}
-
-// Использование
-createUser({
-    name: 'Jack',
-    password: '123456',
-    address: 'NY US'
-});
+cp -r node_modules/ts-openapi-codegen/skills ./openapi-codegen-skills
 ```
 
-### Enums vs. Union Types `--useUnionTypes`
-Спецификация OpenAPI позволяет определять [enums](https://swagger.io/docs/specification/data-models/enums/) внутри
-модели данных. По умолчанию мы конвертируем эти определения enums в [TypeScript enums](https://www.typescriptlang.org/docs/handbook/enums.html).
-Однако эти enums объединяются внутри namespace модели, что не поддерживается Babel, [см. документацию](https://babeljs.io/docs/en/babel-plugin-transform-typescript#impartial-namespace-support).
-Поскольку мы также хотим поддерживать проекты, использующие Babel [@babel/plugin-transform-typescript](https://babeljs.io/docs/en/babel-plugin-transform-typescript),
-мы предлагаем флаг `--useUnionTypes` для генерации [union типов](https://www.typescriptlang.org/docs/handbook/unions-and-intersections.html#union-types)
-вместо традиционных enums. Разницу можно увидеть ниже:
-
-**Enums:**
-```typescript
-// Модель
-export interface Order {
-    id?: number;
-    quantity?: number;
-    status?: Order.status;
-}
+Подробнее: [skills/README.md](skills/README.md) — пути для Cursor, Claude Code, Codex и список навыков.
 
-export namespace Order {
-    export enum status {
-        PLACED = 'placed',
-        APPROVED = 'approved',
-        DELIVERED = 'delivered',
-    }
-}
+## Документация
 
-// Использование
-const order: Order = {
-    id: 1,
-    quantity: 40,
-    status: Order.status.PLACED
-}
-```
-
-**Union Types:**
-```typescript
-// Модель
-export interface Order {
-    id?: number;
-    quantity?: number;
-    status?: 'placed' | 'approved' | 'delivered';
-}
-
-// Использование
-const order: Order = {
-    id: 1,
-    quantity: 40,
-    status: 'placed'
-}
-```
-
-### Схемы проверки `--validationLibrary`
-По умолчанию генератор OpenAPI экспортирует только интерфейсы для ваших моделей. Эти интерфейсы помогут вам во время
-разработки, но не будут доступны в JavaScript во время выполнения. Однако OpenAPI позволяет определять свойства,
-которые могут быть полезны во время выполнения, например: `maxLength` строки или `pattern` для сопоставления и т.д.
-
-Параметр `--validationLibrary` позволяет генерировать схемы валидации времени выполнения с использованием популярных библиотек валидации:
-- **none** (по умолчанию) - Схемы валидации не генерируются
-- **zod** - Генерация схем валидации Zod
-- **joi** - Генерация схем валидации Joi
-- **yup** - Генерация схем валидации Yup
-- **jsonschema** - Генерация схем валидации JSON Schema
-
-Если включен `--useHistory` и в diff‑отчёте есть смена типа, валидаторы будут пытаться выполнять коэрсинг:
-- **Zod** использует `z.coerce.*`
-- **Joi** использует `Joi.alternatives().try(...)`
-- **Yup** использует `.transform(...)`
-- **JSON Schema (AJV)** включает `coerceTypes`
-
-### Режим моделей `--modelsMode`
-
-По умолчанию модели генерируются как интерфейсы/типы. При `--modelsMode classes` генератор создаёт:
-- `*Raw` интерфейсы (JSON‑формат API)
-- `*Dto` классы с геттерами, дефолтами, рекурсивными конструкторами и `toJSON()`
-
-Вывод консолидируется в один файл `models.ts`, а `BaseDto`/`dtoUtils` добавляются в `core`.
-
-Допустим, у нас есть следующая модель:
-
-```json
-{
-    "MyModel": {
-        "required": [
-            "key",
-            "name"
-        ],
-        "type": "object",
-        "properties": {
-            "key": {
-                "maxLength": 64,
-                "pattern": "^[a-zA-Z0-9_]*$",
-                "type": "string"
-            },
-            "name": {
-                "maxLength": 255,
-                "type": "string"
-            },
-            "enabled": {
-                "type": "boolean",
-                "readOnly": true
-            },
-            "modified": {
-                "type": "string",
-                "format": "date-time",
-                "readOnly": true
-            }
-        }
-    }
-}
-```
-
-**С Zod (`--validationLibrary zod`):**
-
-```ts
-import { z } from 'zod';
-
-export const MyModelSchema = z.object({
-    key: z.string().max(64).regex(/^[a-zA-Z0-9_]*$/),
-    name: z.string().max(255),
-    enabled: z.boolean().readonly().optional(),
-    modified: z.string().datetime().readonly().optional(),
-});
-
-export type MyModel = z.infer<typeof MyModelSchema>;
-
-export function validateMyModel(data: unknown): MyModel {
-    return MyModelSchema.parse(data);
-}
-
-export function safeValidateMyModel(data: unknown): { success: true; data: MyModel } | { success: false; error: z.ZodError } {
-    const result = MyModelSchema.safeParse(data);
-    if (result.success) {
-        return { success: true, data: result.data };
-    }
-    return { success: false, error: result.error };
-}
-```
-
-**С Joi (`--validationLibrary joi`):**
-
-```ts
-import Joi from 'joi';
-
-export const MyModelSchema = Joi.object({
-    key: Joi.string().max(64).pattern(/^[a-zA-Z0-9_]*$/).required(),
-    name: Joi.string().max(255).required(),
-    enabled: Joi.boolean().readonly(),
-    modified: Joi.string().isoDate().readonly(),
-});
-```
-
-**С Yup (`--validationLibrary yup`):**
-
-```ts
-import * as yup from 'yup';
-
-export const MyModelSchema = yup.object({
-    key: yup.string().max(64).matches(/^[a-zA-Z0-9_]*$/).required(),
-    name: yup.string().max(255).required(),
-    enabled: yup.boolean().readonly(),
-    modified: yup.string().datetime().readonly(),
-});
-```
-
-**С JSON Schema (`--validationLibrary jsonschema`):**
-
-```ts
-export const MyModelSchema = {
-    type: 'object',
-    required: ['key', 'name'],
-    properties: {
-        key: {
-            type: 'string',
-            maxLength: 64,
-            pattern: '^[a-zA-Z0-9_]*$',
-        },
-        name: {
-            type: 'string',
-            maxLength: 255,
-        },
-        enabled: {
-            type: 'boolean',
-            readOnly: true,
-        },
-        modified: {
-            type: 'string',
-            format: 'date-time',
-            readOnly: true,
-        },
-    },
-};
-```
-
-Эти схемы валидации могут быть использованы для генерации форм, валидации ввода и проверки типов во время выполнения в вашем приложении.
-
-### Отменяемый promise `--useCancelableRequest`
-По умолчанию генератор OpenAPI генерирует сервисы для доступа к API, которые используют неотменяемые запросы. Поэтому мы добавили возможность переключить генератор на генерацию отменяемых API запросов. Для этого используйте флаг `--useCancelableRequest`.
-Пример отменяемого запроса будет выглядеть так:
-
-```typescript
-export function request<T>(config: TOpenAPIConfig, options: ApiRequestOptions): CancelablePromise<T> {
-    return new CancelablePromise(async(resolve, reject, onCancel) => {
-        const url = `${config.BASE}${options.path}`.replace('{api-version}', config.VERSION);
-        try {
-            if (!onCancel.isCancelled) {
-                const response = await sendRequest(options, url, config, onCancel);
-                const responseBody = await getResponseBody(response);
-                const responseHeader = getResponseHeader(response, options.responseHeader);
-                const result: ApiResult = {
-                    url,
-                    ok: response.ok,
-                    status: response.status,
-                    statusText: response.statusText,
-                    body: responseHeader || responseBody,
-                };
-
-                catchErrors(options, result);
-                resolve(result.body);
-            }
-        } catch (e) {
-            reject(e);
-        }
-    });
-}
-```
-
-### RequestExecutor
-
-Начиная с версии **2.0.0**, сгенерированные сервисы используют интерфейс `RequestExecutor`
-вместо прямых вызовов core-функции `request`.
-
-`RequestExecutor` — это единая точка интеграции HTTP-логики, отвечающая за выполнение запросов
-и расширение поведения клиента. Он позволяет:
-- использовать любой транспорт (fetch / axios / xhr / custom);
-- централизованно обрабатывать запросы, ответы и ошибки;
-- расширять поведение клиента без изменения сгенерированных сервисов.
-
-#### Interceptors
-
-`RequestExecutor` поддерживает **interceptors**, которые позволяют внедрять дополнительную
-логику на разных этапах жизненного цикла запроса:
-
-- `onRequest` — модификация запроса перед отправкой (headers, auth, логирование);
-- `onResponse` — обработка успешных ответов;
-- `onError` — централизованная обработка ошибок.
-
-Interceptors применяются на уровне executor’а и автоматически используются всеми
-сгенерированными сервисами.
-
-```ts
-import { createClient } from './generated';
-
-const client = createClient({
-    interceptors: {
-        onRequest: [
-            (config) => ({
-                ...config,
-                headers: {
-                    ...config.headers,
-                    Authorization: 'Bearer token',
-                },
-            }),
-        ],
-        onError: [
-            (error) => {
-                console.error(error);
-                throw error;
-            },
-        ],
-    },
-});
-```
-
-#### Пользовательская реализация RequestExecutor с interceptors
-
-Пользовательский `RequestExecutor` может быть использован вместе с interceptors.
-В этом случае executor отвечает только за транспорт и выполнение запроса,
-а interceptors — за расширяемую бизнес-логику (авторизация, логирование, обработка ошибок).
-
-```ts
-import type { RequestExecutor, RequestConfig } from './generated/core/executor/requestExecutor';
-import { withInterceptors } from './generated/core/interceptors/withInterceptors';
-import { SimpleService } from './generated/services/SimpleService';
-
-interface MyCustomOptions {
-    timeout?: number;
-}
-
-const baseExecutor: RequestExecutor<MyCustomOptions> = {
-    async request<T>(config: RequestConfig, options?: MyCustomOptions): Promise<T> {
-        const response = await fetch(config.url, {
-            method: config.method,
-            headers: config.headers,
-            body: config.body ? JSON.stringify(config.body) : undefined,
-            signal: options?.timeout
-                ? AbortSignal.timeout(options.timeout)
-                : undefined,
-        });
-
-        if (!response.ok) {
-            throw new Error(`Request failed: ${response.status}`);
-        }
-
-        return response.json();
-    },
-};
-
-// Оборачиваем executor interceptors
-const executor = withInterceptors(baseExecutor, {
-    onRequest: [
-        (config) => ({
-            ...config,
-            headers: {
-                ...config.headers,
-                Authorization: 'Bearer token',
-            },
-        }),
-    ],
-    onError: [
-        (error) => {
-            console.error(error);
-            throw error;
-        },
-    ],
-});
-
-const service = new SimpleService(executor);
-await service.getCallWithoutParametersAndResponse({ timeout: 5000 });
-```
-
-#### Использование сгенерированного `createClient` с `customExecutorPath` и `executorFactory`
-
-Если в конфигурации генерации задан `customExecutorPath`, в `createClient.ts` будет импортирован ваш
-пользовательский `createExecutorAdapter`, и он станет базовым executor по умолчанию.
-
-Дополнительно в runtime можно передать `executorFactory`, чтобы обернуть/расширить этот базовый executor
-(retry, tracing, metrics и т.д.) без изменения сгенерированных сервисов.
-
-```ts
-import { createClient } from './generated';
-
-const client = createClient({
-    executorFactory: ({ openApiConfig, createDefaultExecutor }) => {
-        const baseExecutor = createDefaultExecutor();
-
-        return {
-            async request<TResponse>(config, options) {
-                console.debug('Request to', openApiConfig.BASE, config.path);
-                return baseExecutor.request<TResponse>(config, options);
-            },
-        };
-    },
-});
-```
-
-### Стратегия сортировки аргументов функций `--sortByRequired`
-По умолчанию генератор OpenAPI сортирует параметры сервисных функций согласно упрощенной схеме. Если вам нужна более строгая опция сортировки, используйте флаг `--sortByRequired`. Упрощенная опция сортировки похожа на ту, что использовалась в версии 0.2.3 генератора OpenAPI. Этот флаг позволяет обновиться до новой версии генератора, если вы "застряли" на версии 0.2.3.
-
-### Отдельные index файлы `--useSeparatedIndexes`
-По умолчанию генератор создает один index файл, который экспортирует весь сгенерированный код. С флагом `--useSeparatedIndexes` вы можете генерировать отдельные index файлы для core, models, schemas и services, что может помочь с лучшей организацией кода и tree-shaking.
-
-### Enum с пользовательскими именами и описаниями
-Вы можете использовать `x-enum-varnames` и `x-enum-descriptions` в вашей спецификации для генерации enum с пользовательскими именами и описаниями.
-Это еще не в официальной [спецификации](https://github.com/OAI/OpenAPI-Specification/issues/681). Но это поддерживаемое расширение,
-которое может помочь разработчикам использовать более осмысленные перечислители.
-```json
-{
-    "EnumWithStrings": {
-        "description": "This is a simple enum with strings",
-        "enum": [
-            0,
-            1,
-            2
-        ],
-        "x-enum-varnames": [
-            "Success",
-            "Warning",
-            "Error"
-        ],
-        "x-enum-descriptions": [
-            "Used when the status of something is successful",
-            "Used when the status of something has a warning",
-            "Used when the status of something has an error"
-        ]
-    }
-}
-```
-
-Сгенерированный код:
-```typescript
-enum EnumWithStrings {
-    /*
-    * Used when the status of something is successful
-    */
-    Success = 0,
-    /*
-    * Used when the status of something has a warning
-    */
-    Waring = 1,
-    /*
-    * Used when the status of something has an error
-    */
-    Error = 2,
-}
-```
-
-
-### Nullable в OpenAPI v2
-В спецификации OpenAPI v3 вы можете создавать свойства, которые могут быть NULL, указав `nullable: true` в вашей схеме.
-Однако спецификация v2 не позволяет этого делать. Вы можете использовать неофициальный `x-nullable` в вашей спецификации
-для генерации nullable свойств в OpenApi v2.
-
-```json
-{
-    "ModelWithNullableString": {
-        "required": ["requiredProp"],
-        "description": "This is a model with one string property",
-        "type": "object",
-        "properties": {
-            "prop": {
-                "description": "This is a simple string property",
-                "type": "string",
-                "x-nullable": true
-            },
-            "requiredProp": {
-                "description": "This is a simple string property",
-                "type": "string",
-                "x-nullable": true
-            }
-        }
-    }
-}
-```
-
-Сгенерированный код:
-```typescript
-interface ModelWithNullableString {
-    prop?: string | null,
-    requiredProp: string | null,
-}
-```
-
-
-### Авторизация
-Генератор OpenAPI поддерживает авторизацию Bearer Token. Для включения отправки
-токенов в каждом запросе вы можете установить токен используя глобальную конфигурацию OpenAPI:
-
-```typescript
-import { OpenAPI } from './generated';
-
-OpenAPI.TOKEN = 'some-bearer-token';
-```
-
-Альтернативно, мы также поддерживаем асинхронный метод, который предоставляет токен для каждого запроса.
-Вы можете просто назначить этот метод тому же свойству `TOKEN` в глобальном объекте OpenAPI.
-
-```typescript
-import { OpenAPI } from './generated';
-
-const getToken = async () => {
-    // Какой-то код, который запрашивает токен...
-    return 'SOME_TOKEN';
-}
-
-OpenAPI.TOKEN = getToken;
-```
-
-### Ссылки
-
-Локальные ссылки на определения схем (начинающиеся с `#/definitions/schemas/`)
-будут преобразованы в ссылки на типы к эквивалентному сгенерированному типу верхнего уровня.
-
-Генератор OpenAPI также поддерживает внешние ссылки, что позволяет разбить
-ваш openapi.yml на несколько подфайлов или включить сторонние схемы
-как часть ваших типов, чтобы обеспечить возможность генерации TypeScript для всего.
-
-Внешние ссылки могут быть:
-* *относительными ссылками* - ссылки на другие файлы в том же расположении, например
-    `{ $ref: 'schemas/customer.yml' }`
-* *удаленными ссылками* - полностью квалифицированные ссылки на другое удаленное расположение
-     например `{ $ref: 'https://myexampledomain.com/schemas/customer_schema.yml' }`
-
-    Для удаленных ссылок поддерживаются как файлы (когда файл находится в текущей файловой системе),
-    так и http(s) URL.
-
-Внешние ссылки также могут содержать внутренние пути во внешней схеме (например,
-`schemas/collection.yml#/definitions/schemas/Customer`) и обратные ссылки на
-базовый файл openapi или между файлами (так что вы можете ссылаться на другую
-схему в главном файле как тип свойства объекта или массива, например).
-
-При запуске файл OpenAPI или Swagger с внешними ссылками будет "собран",
-так что все внешние ссылки и обратные ссылки будут разрешены (но локальные
-ссылки сохранены).
-
-FAQ
-===
-
-### Поддержка Babel
-Если вы используете enums внутри ваших моделей / определений, то эти enums по умолчанию находятся внутри namespace с тем же именем,
-что и ваша модель. Это называется объединением объявлений. Однако [@babel/plugin-transform-typescript](https://babeljs.io/docs/en/babel-plugin-transform-typescript)
-не поддерживает эти namespace, поэтому если вы используете babel в вашем проекте, пожалуйста используйте флаг `--useUnionTypes`
-для генерации union типов вместо традиционных enums. Больше информации можно найти здесь: [Enums vs. Union Types](#enums-vs-union-types---useuniontypes).
-
-**Примечание:** Если вы используете Babel 7 и Typescript 3.8 (или выше), то вы должны включить `onlyRemoveTypeImports` для
-игнорирования любых импортов 'type only', см. https://babeljs.io/docs/en/babel-preset-typescript#onlyremovetypeimports для большей информации
-
-```javascript
-module.exports = {
-    presets: [
-        ['@babel/preset-typescript', {
-            onlyRemoveTypeImports: true,
-        }],
-    ],
-};
-```
-
-
-### Поддержка Node.js
-По умолчанию эта библиотека будет генерировать клиент, совместимый с (браузерным) [fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API),
-однако этот клиент не будет работать в среде Node.js. Если вы хотите сгенерировать клиент, совместимый с Node.js, то
-вы можете указать `--httpClient node` в вызове openapi:
-
-`openapi generate --input ./spec.json --output ./dist --httpClient node`
-
-Это сгенерирует клиент, который использует [`node-fetch`](https://www.npmjs.com/package/node-fetch) внутри. Однако,
-для компиляции и запуска этого клиента вам нужно установить зависимости `node-fetch`:
-
-```
-npm install @types/node-fetch --save-dev
-npm install node-fetch --save-dev
-npm install form-data --save-dev
-```
-
-Для компиляции проекта и разрешения импортов вам нужно включить `allowSyntheticDefaultImports`
-в вашем файле `tsconfig.json`.
-
-```json
-{
-    "allowSyntheticDefaultImports": true
-}
-```
+- [Использование](docs/ru/usage.md)
+- [Файл конфигурации](docs/ru/configuration.md)
+- [Примеры](docs/ru/examples.md)
+- [Возможности](docs/ru/features.md)
+- [Руководство по миграции](MIGRATION.RU.md)
+- [Плагины](docs/ru/plugins.md)
+- [Plugin API v2 (RFC)](docs/ru/plugin-api-v2.md)
+- [English README](README.md)
+- [English docs](docs/en/usage.md)
 
 [npm-url]: https://www.npmjs.com/package/ts-openapi-codegen
 [npm-image]: https://img.shields.io/npm/v/ts-openapi-codegen.svg