ts-openapi-codegen 2.0.0 → 2.1.0-beta.2

package/README.md

@@ -28,6 +28,7 @@
 - Supports tsc and @babel/plugin-transform-typescript
 - Supports customization names of models
 - Supports external references using [`swagger-parser`](https://github.com/APIDevTools/swagger-parser/)
+- Supports binary request/response generation (`format: binary` -> `Blob`)
 
 ## Install
 
@@ -38,7 +39,7 @@ npm install ts-openapi-codegen --save-dev
 
 ## Usage
 
-The CLI tool supports five commands: `generate`, `check-config`, `update-config`, `init`, and `preview-changes`.
+The CLI tool supports six commands: `generate`, `check-config`, `update-config`, `init`, `preview-changes`, and `analyze-diff`.
 
 ### Command: `generate`
 
@@ -72,10 +73,15 @@ openapi generate --input ./spec.json --output ./dist
 | `--useCancelableRequest` | - | boolean | `false` | Use cancelable promise as return type |
 | `--sortByRequired` | `-s` | boolean | `false` | Use extended sorting strategy for function arguments |
 | `--useSeparatedIndexes` | - | boolean | `false` | Use separate index files for core, models, schemas, and services |
+| `--strict-openapi` | - | boolean | `false` | Enable strict OpenAPI diagnostics and fail generation when strict errors are found |
+| `--report-file` | - | string | `./openapi-report.json` | Path to strict OpenAPI diagnostics report JSON file |
 | `--logLevel` | `-l` | string | `error` | Logging level: `info`, `warn`, or `error` |
 | `--logTarget` | `-t` | string | `console` | Logging target: `console` or `file` |
 | `--validationLibrary` | - | string | `none` | Validation library for schema generation: `none`, `zod`, `joi`, `yup`, or `jsonschema` |
 | `--emptySchemaStrategy` | - | string | `keep` | Strategy for empty schemas: `keep`, `semantic`, or `skip` |
+| `--modelsMode` | - | string | `interfaces` | Models generation mode: `interfaces` or `classes` |
+| `--useHistory` | - | boolean | `false` | Apply diff report annotations during generation |
+| `--diffReport` | - | string | `./openapi-diff-report.json` | Path to diff report JSON |
 
 **Examples:**
 ```bash
@@ -163,6 +169,46 @@ openapi preview-changes --openapi-config ./custom-config.json
 - `--preview-dir` / `-pd` - Temporary preview generation directory (default: `./.ts-openapi-codegen-preview-changes`)
 - `--diff-dir` / `-dd` - Directory for diff reports (default: `./.ts-openapi-codegen-diff-changes`)
 
+### Command: `analyze-diff`
+
+Analyzes differences between two OpenAPI specifications and produces a JSON report.
+
+**Usage:**
+```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
+```
+
+**Options:**
+- `--input` / `-i` - Path to current OpenAPI specification file (required)
+- `--compare-with` - Path to previous OpenAPI specification file
+- `--git` - Git ref to read previous specification version from (e.g. `HEAD~1`)
+- `--output-report` - Path to save JSON diff report (default: `./openapi-diff-report.json`)
+
+#### Miracles and confirmation
+
+The diff report can contain a `miracles` section with detected renames/type-coercions. Only confirmed miracles are applied in generation.
+
+**How to confirm miracles:**
+1. Run `analyze-diff` and open the generated report (default: `./openapi-diff-report.json`).
+2. Find the entry in `miracles` you want to accept.
+3. Change `"status": "auto-generated"` to `"status": "confirmed"` and commit the report.
+
+Example (excerpt):
+```json
+{
+  "miracles": [
+    {
+      "oldPath": "$.components.schemas.User.properties.user_name",
+      "newPath": "$.components.schemas.User.properties.userName",
+      "type": "RENAME",
+      "confidence": 0.85,
+      "status": "confirmed"
+    }
+  ]
+}
+```
+
 ### Configuration File
 
 Instead of passing all options via CLI, you can use a configuration file. Create `openapi.config.json` in your project root:
@@ -183,7 +229,22 @@ Instead of passing all options via CLI, you can use a configuration file. Create
     "sortByRequired": false,
     "useSeparatedIndexes": false,
     "request": "./custom-request.ts",
-    "customExecutorPath": "./custom/createExecutorAdapter.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"]
+    }
 }
 ```
 
@@ -241,9 +302,17 @@ Instead of passing all options via CLI, you can use a configuration file. Create
 | `useCancelableRequest` | boolean | `false` | Use cancelable promise as return type |
 | `sortByRequired` | boolean | `false` | Extended sorting strategy for arguments |
 | `useSeparatedIndexes` | boolean | `false` | Use separate index files |
+| `strictOpenapi` | boolean | `false` | Enable strict OpenAPI diagnostics and fail generation on strict errors |
+| `reportFile` | string | `./openapi-report.json` | Path to strict OpenAPI diagnostics report JSON file |
 | `items` | array | - | Array of configurations (for multi-options format) |
 | `validationLibrary` | string | `none` | Validation library for schema generation: `none`, `zod`, `joi`, `yup`, or `jsonschema` |
 | `emptySchemaStrategy` | string | `keep` | Strategy for empty schemas: `keep`, `semantic`, or `skip` |
+| `modelsMode` | string | `interfaces` | Models generation mode: `interfaces` or `classes` |
+| `useHistory` | boolean | `false` | Apply diff report annotations during generation |
+| `diffReport` | string | `./openapi-diff-report.json` | Path to diff report JSON |
+| `models` | object | - | Models config section (e.g. `mode`) |
+| `analyze` | object | - | Analyze config section (e.g. reportPath, useHistory, ignore) |
+| `miracles` | object | - | Miracles config section (enabled, confidence, types) |
 
 **Note:** You can use the `init` command to generate a template configuration file.
 
@@ -265,6 +334,16 @@ openapi init
 openapi generate
 ```
 
+**With DTO models (classes mode):**
+```bash
+openapi generate --input ./spec.json --output ./dist --modelsMode classes
+```
+
+**Generate diff report:**
+```bash
+openapi analyze-diff --input ./openapi/current.yaml --compare-with ./openapi/previous.yaml --output-report ./openapi-diff-report.json
+```
+
 **Check configuration:**
 ```bash
 openapi check-config
@@ -423,6 +502,20 @@ The `--validationLibrary` parameter allows you to generate runtime validation sc
 - **yup** - Generate Yup validation schemas
 - **jsonschema** - Generate JSON Schema validation schemas
 
+When `--useHistory` is enabled and a diff report marks a type change, validators will attempt to coerce values:
+- **Zod** uses `z.coerce.*`
+- **Joi** uses `Joi.alternatives().try(...)`
+- **Yup** uses `.transform(...)`
+- **JSON Schema (AJV)** enables `coerceTypes`
+
+### Models mode `--modelsMode`
+
+By default, models are generated as TypeScript interfaces/types. When `--modelsMode classes` is used, the generator produces:
+- `*Raw` interfaces matching the API JSON
+- `*Dto` classes with getters, defaults, recursive constructors, and `toJSON()`
+
+The output is consolidated into a single `models.ts` file, and `BaseDto`/`dtoUtils` are emitted in `core`.
+
 Let's say we have the following model:
 
 ```json

package/README.rus.md

@@ -28,6 +28,7 @@
 - Поддерживает tsc и @babel/plugin-transform-typescript
 - Поддерживает кастомизацию имен моделей
 - Поддерживает внешние ссылки с помощью [`swagger-parser`](https://github.com/APIDevTools/swagger-parser/)
+- Поддерживает генерацию бинарных request/response (`format: binary` -> `Blob`)
 
 ## Установка
 
@@ -37,7 +38,7 @@ npm install ts-openapi-codegen --save-dev
 
 ## Использование
 
-CLI инструмент поддерживает пять команд: `generate`, `check-config`, `update-config`, `init` и `preview-changes`.
+CLI инструмент поддерживает шесть команд: `generate`, `check-config`, `update-config`, `init`, `preview-changes` и `analyze-diff`.
 
 ### Команда: `generate`
 
@@ -71,10 +72,15 @@ openapi generate --input ./spec.json --output ./dist
 | `--useCancelableRequest` | - | boolean | `false` | Использовать отменяемый promise как тип возврата |
 | `--sortByRequired` | `-s` | boolean | `false` | Использовать расширенную стратегию сортировки для аргументов функций |
 | `--useSeparatedIndexes` | - | boolean | `false` | Использовать отдельные index файлы для core, models, schemas и services |
+| `--strict-openapi` | - | boolean | `false` | Включить строгую диагностику OpenAPI и завершать генерацию при strict-ошибках |
+| `--report-file` | - | string | `./openapi-report.json` | Путь к JSON-файлу strict-отчета по диагностике OpenAPI |
 | `--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
@@ -162,6 +168,46 @@ openapi preview-changes --openapi-config ./custom-config.json
 - `--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` в корне вашего проекта:
@@ -182,7 +228,22 @@ openapi preview-changes --openapi-config ./custom-config.json
     "sortByRequired": false,
     "useSeparatedIndexes": false,
     "request": "./custom-request.ts",
-    "customExecutorPath": "./custom/createExecutorAdapter.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"]
+    }
 }
 ```
 
@@ -240,9 +301,17 @@ openapi preview-changes --openapi-config ./custom-config.json
 | `useCancelableRequest` | boolean | `false` | Использовать отменяемый promise как тип возврата |
 | `sortByRequired` | boolean | `false` | Расширенная стратегия сортировки для аргументов |
 | `useSeparatedIndexes` | boolean | `false` | Использовать отдельные index файлы |
+| `strictOpenapi` | boolean | `false` | Включить строгую диагностику OpenAPI и падать на strict-ошибках |
+| `reportFile` | string | `./openapi-report.json` | Путь к JSON-файлу strict-отчета по диагностике OpenAPI |
 | `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` для генерации шаблона файла конфигурации.
 
@@ -264,6 +333,16 @@ 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
@@ -422,6 +501,20 @@ const order: Order = {
 - **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

package/dist/cli/analyzeDiff/__tests__/analyzeDiff.cli.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=analyzeDiff.cli.test.d.ts.map

package/dist/cli/analyzeDiff/__tests__/analyzeDiff.cli.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzeDiff.cli.test.d.ts","sourceRoot":"","sources":["../../../../src/cli/analyzeDiff/__tests__/analyzeDiff.cli.test.ts"],"names":[],"mappings":""}