npm package: @owndo/openapi-typescript-codegen
Description: Fork of: https://github.com/ferdikoomen/openapi-typescript-codegen. Library that generates Typescript clients based on the OpenAPI specification.
Author: Endless
Latest version: 0.0.5

# OpenAPI Typescript Codegen

> 基于 OpenAPI 规范生成 TypeScript 客户端的 Node.js 库

这是一个基于 [openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen) 的 fork 版本。

## 特性

- 🚀 快速、轻量、健壮且框架无关
- 📦 支持生成 TypeScript 客户端
- 🌐 支持生成多种 HTTP 客户端：Fetch、Node-Fetch、Axios、Angular 和 XHR
- 📋 支持 OpenAPI 规范 v2.0 和 v3.0
- 📄 支持 JSON 和 YAML 格式的输入文件
- 💻 支持通过 CLI、Node.js 和 NPX 使用
- 🔧 支持 tsc 和 @babel/plugin-transform-typescript
- ⏹️ 支持请求中止（可取消的 Promise 模式）
- 🔗 支持使用 [json-schema-ref-parser](https://github.com/APIDevTools/json-schema-ref-parser/) 处理外部引用

## 安装

```bash
npm install @owndo/openapi-typescript-codegen --save-dev
```

## 使用方法

### CLI 命令行

```bash
$ openapi --help

  Usage: openapi [options]

  Options:
    -V, --version             output the version number
    -i, --input <value>       OpenAPI specification, can be a path, url or string content (required)
    -o, --output <value>      Output directory (required)
    -c, --client <value>      HTTP client to generate [fetch, xhr, node, axios, angular] (default: "fetch")
    --name <value>            Custom client class name
    --useOptions              Use options instead of arguments
    --useUnionTypes           Use union types instead of enums
    --exportCore <value>      Write core files to disk (default: true)
    --exportServices <value>  Write services to disk (default: true)
    --exportModels <value>    Write models to disk (default: true)
    --exportSchemas <value>   Write schemas to disk (default: false)
    --indent <value>          Indentation options [4, 2, tabs] (default: "4")
    --postfixServices <value> Service name postfix (default: "Service")
    --postfixModels <value>   Model name postfix
    --request <value>         Path to custom request file
    --keepOnlyMainService     Keep only the main service and remove others (default: false, keeps all services)
    -h, --help                display help for command

  Examples
    $ openapi --input ./spec.json --output ./generated
    $ openapi --input ./spec.json --output ./generated --client xhr
    $ openapi --input https://api.example.com/openapi.json --output ./generated --client axios
```

### Node.js API

```typescript
import { generate, HttpClient } from '@owndo/openapi-typescript-codegen';

await generate({
    input: './spec.json',
    output: './generated',
    httpClient: HttpClient.FETCH,
    clientName: 'ApiClient',
    useOptions: false,
    useUnionTypes: false,
    exportCore: true,
    exportServices: true,
    exportModels: true,
    exportSchemas: false,
    indent: '4',
    postfixServices: 'Service',
    postfixModels: '',
    keepOnlyMainService: false, // 是否仅保留主服务（默认：false，保留所有服务）
    // 自定义操作名称转换函数（可选）
    transformOperationName: (url: string, method: string, operationId?: string) => {
        // 自定义逻辑：例如使用 operationId 或组合 url 和 method
        if (operationId) {
            return operationId;
        }
        return `${method.toUpperCase()}_${url.replace(/\//g, '_').replace(/[{}]/g, '')}`;
    },
});
```

## 支持的 HTTP 客户端

- **fetch** - 使用浏览器原生 Fetch API（默认）
- **xhr** - 使用 XMLHttpRequest
- **node** - 使用 Node.js 的 node-fetch
- **axios** - 使用 Axios 库
- **angular** - 使用 Angular 的 HttpClient

## 与原始仓库的改动

本 fork 版本在原始项目 [ferdikoomen/openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen) 的基础上进行了以下改动：

### 功能增强

1. **Schema 属性展开功能**
   - 新增 `expandSchemaProperties` 函数，支持将 schema 引用展开为独立的操作参数
   - 当 query、formData 或 requestBody 参数使用 schema 引用时，会自动展开为多个独立的参数
   - 适用于 OpenAPI v2.0 和 v3.0 规范

2. **参数处理改进**
   - 在 `OperationParameters` 接口中新增 `parametersBodyExpanded` 字段
   - 改进了 query 和 formData 参数的处理逻辑，支持 schema 引用的自动展开
   - 增强了 requestBody 的处理，支持将复杂 schema 展开为多个参数

3. **操作名称自定义转换功能**
   - 新增 `transformOperationName` 选项，允许自定义操作名称的生成逻辑
   - 支持根据 URL、HTTP 方法和 operationId 自定义生成操作名称
   - 适用于 OpenAPI v2.0 和 v3.0 规范
   - 可通过 Node.js API 使用（CLI 暂不支持函数参数）

4. **多服务合并功能**
   - 自动识别主服务（通常是名称最短且作为其他服务名称前缀的服务）
   - 自动将其他服务的所有操作合并到主服务中，使主服务可以访问所有 API
   - 支持 `keepOnlyMainService` 选项，当设置为 `true` 时仅保留主服务，移除其他服务
   - 默认保留所有服务，同时主服务包含所有 API 操作
   - 自动处理操作名称冲突，通过添加服务名前缀避免冲突

### 项目配置变更

1. **包名和仓库**
   - 包名从 `openapi-typescript-codegen` 变更为 `@owndo/openapi-typescript-codegen`
   - 仓库地址更新为 [xujiehui/openapi-typescript-codegen](https://github.com/xujiehui/openapi-typescript-codegen)

2. **版本信息**
   - 当前版本：0.0.1
   - 作者：Endless

### 使用说明

这些改动向后兼容，不会影响现有功能。新增的 schema 展开功能会在检测到 schema 引用时自动启用，无需额外配置。

#### transformOperationName 使用示例

`transformOperationName` 函数接收三个参数：
- `url`: API 路径（例如：`/api/users/{id}`）
- `method`: HTTP 方法（例如：`get`, `post`, `put`）
- `operationId`: OpenAPI 规范中定义的 operationId（可选）

函数应返回一个字符串作为生成的操作名称。如果不提供此函数，将使用默认的命名规则。

```typescript
// 示例 1: 使用 operationId（如果存在）
transformOperationName: (url, method, operationId) => {
    return operationId || `${method}${url.split('/').pop()}`;
}

// 示例 2: 自定义命名规则
transformOperationName: (url, method, operationId) => {
    const pathParts = url.split('/').filter(Boolean);
    const resource = pathParts[pathParts.length - 1] || 'default';
    return `${method.toUpperCase()}_${resource}`;
}

// 示例 3: 移除路径参数并格式化
transformOperationName: (url, method, operationId) => {
    const cleanUrl = url.replace(/\{[^}]+\}/g, '').replace(/\//g, '_');
    return `${method}_${cleanUrl}`.replace(/^_|_$/g, '');
}
```

如果你需要从原始仓库迁移到本 fork 版本，只需更改包名即可：

```bash
# 原始版本
npm install openapi-typescript-codegen --save-dev

# Fork 版本
npm install @owndo/openapi-typescript-codegen --save-dev
```

## 项目信息

- **包名**: `@owndo/openapi-typescript-codegen`
- **版本**: 0.0.1
- **许可证**: MIT
- **仓库**: [GitHub](https://github.com/xujiehui/openapi-typescript-codegen)
- **问题反馈**: [Issues](https://github.com/xujiehui/openapi-typescript-codegen/issues)

## 开发

```bash
# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm test

# 运行端到端测试
npm run test:e2e

# 代码检查
npm run eslint

# 代码格式化
npm run eslint:fix
```

## 许可证

MIT License

## 致谢

本项目基于 [ferdikoomen/openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen) 项目 fork 而来。