GitHub Repo stars npm (scoped) GitHub tag (latest SemVer pre-release)

English | 中文

A powerful tool that generates TypeScript request code from OpenAPI 3.0 documentation. If you're using umi, you might want to check out @umijs/plugin-openapi plugin instead.

npm i --save-dev @umijs/openapi
# or
pnpm add -D @umijs/openapi
# or
yarn add -D @umijs/openapi

1. Create a configuration file in your project root directory. You can name it either openapi2ts.config.ts or .openapi2tsrc.ts:

export default {
 schemaPath: 'http://petstore.swagger.io/v2/swagger.json',
 serversPath: './servers',
}

For multiple API sources, you can use an array configuration:

export default [
 {
 schemaPath: 'http://app.swagger.io/v2/swagger.json',
 serversPath: './servers/app',
 },
 {
 schemaPath: 'http://auth.swagger.io/v2/swagger.json',
 serversPath: './servers/auth',
 }
]

2. Add the generation script to your package.json:

{
 "scripts": {
 "openapi2ts": "openapi2ts"
 }
}

3. Generate the API code:

npm run openapi2ts

The apiPrefix option allows you to add a prefix to all generated API paths. It can be:

• A string literal: apiPrefix: "'/api'" - The prefix will be processed as a string value
• A function that returns a string: apiPrefix: (data) => "/api" - Dynamically determine the prefix

The dedupeApiPrefix option controls how to handle prefixes:

• true (default): When the API path already contains the specified prefix, it will be deduplicated (not added again)
  • Example: path /api/user/list with apiPrefix: "'/api'" → remains /api/user/list (not /api/api/user/list)
• false: No deduplication, the prefix will be treated as a variable reference
  • Example: path /user/list with apiPrefix: "'/api'" and dedupeApiPrefix: false → becomes ${'/api'}/user/list

Example configuration:

export default {
 schemaPath: 'http://petstore.swagger.io/v2/swagger.json',
 serversPath: './servers',
 apiPrefix: "'/api'", // or apiPrefix: (data) => "/api"
 dedupeApiPrefix: true, // Deduplicate prefix if it already exists
}

一个强大的工具,可以根据 OpenAPI 3.0 文档生成 TypeScript 请求代码。如果你使用 umi,可以考虑使用 @umijs/plugin-openapi 插件。

npm i --save-dev @umijs/openapi
# 或者
pnpm add -D @umijs/openapi
# 或者
yarn add -D @umijs/openapi

1. 在项目根目录创建配置文件,可以命名为 openapi2ts.config.ts 或 .openapi2tsrc.ts:

export default {
 schemaPath: 'http://petstore.swagger.io/v2/swagger.json',
 serversPath: './servers',
}

如果需要处理多个 API 源,可以使用数组配置:

export default [
 {
 schemaPath: 'http://app.swagger.io/v2/swagger.json',
 serversPath: './servers/app',
 },
 {
 schemaPath: 'http://auth.swagger.io/v2/swagger.json',
 serversPath: './servers/auth',
 }
]

2. 在 package.json 中添加生成脚本:

{
 "scripts": {
 "openapi2ts": "openapi2ts"
 }
}

3. 生成 API 代码:

npm run openapi2ts

apiPrefix 选项用于为生成的所有 API 路径添加前缀,支持两种形式:

• 字符串字面量:apiPrefix: "'/api'" - 前缀将被作为字符串值处理
• 函数:apiPrefix: (data) => "/api" - 动态决定前缀

dedupeApiPrefix 选项控制如何处理前缀:

• true(默认):当 API 路径已包含指定的前缀时,会进行去重处理(不再添加)
  • 示例:路径 /api/user/list,配置 apiPrefix: "'/api'" → 保持 /api/user/list(不会变成 /api/api/user/list)
• false:不进行去重,前缀将被作为变量引用处理
  • 示例:路径 /user/list,配置 apiPrefix: "'/api'" 和 dedupeApiPrefix: false → 生成 ${'/api'}/user/list

配置示例:

export default {
 schemaPath: 'http://petstore.swagger.io/v2/swagger.json',
 serversPath: './servers',
 apiPrefix: "'/api'", // 或者 apiPrefix: (data) => "/api"
 dedupeApiPrefix: true, // 当前缀已存在时进行去重
}