OpenAPI Typescript Codegen

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

这是一个基于 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 处理外部引用

安装

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

使用方法

$3

`bash
$ openapi --help

Usage: openapi [options]

Options:
-V, --version output the version number
-i, --input OpenAPI specification, can be a path, url or string content (required)
-o, --output Output directory (required)
-c, --client HTTP client to generate [fetch, xhr, node, axios, angular] (default: "fetch")
--name Custom client class name
--useOptions Use options instead of arguments
--useUnionTypes Use union types instead of enums
--exportCore Write core files to disk (default: true)
--exportServices Write services to disk (default: true)
--exportModels Write models to disk (default: true)
--exportSchemas Write schemas to disk (default: false)
--indent Indentation options [4, 2, tabs] (default: "4")
--postfixServices Service name postfix (default: "Service")
--postfixModels Model name postfix
--request 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
`

$3

`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 的基础上进行了以下改动：

$3

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 操作
- 自动处理操作名称冲突，通过添加服务名前缀避免冲突

$3

1. 包名和仓库
- 包名从 openapi-typescript-codegen 变更为 @owndo/openapi-typescript-codegen
- 仓库地址更新为 xujiehui/openapi-typescript-codegen

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

$3

这些改动向后兼容，不会影响现有功能。新增的 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
- 问题反馈: 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 项目 fork 而来。