介绍

English | 简体中文

根据 Swagger2/OpenAPI3/Apifox 文档生成:

• TypeScript/JavaScript
• 客户端请求函数(支持任意客户端)
• 模拟请求响应服务
• 枚举和枚举翻译
• react-query/vue-query
• 类型字段翻译
• JSON Schemas
• Apifox Config

文档：使用手册

功能

• 支持 Swagger2.0/OpenAPI/Apifox 3.0,3.1 定义
• 生成 TypeScript/JavaScript, 请求客户端(支持任意客户端), 请求模拟服务, 枚举和枚举翻译, react-query/vue-query, 类型字段翻译, JSON Schemas
• 支持通过 npx、CLI、Nodejs 的方式使用
• 支持自定义请求工具函数, 支持 Fetch、Axios、UniApp-Request、Taro-Request、Node.js、XHR 客户端
• 支持通过 tags 过滤生成结果
• 支持 JSON/YAML 定义文件
• 支持将中文 tag 名称翻译为英文 tag 名称
• 支持直接配置apifox的token和projectId直接生成

使用

# npm
npm i openapi-ts-request --save-dev

# pnpm
pnpm i openapi-ts-request -D

CosmiConfig

在项目根目录新建 openapi-ts-request.config.ts

配置文件还支持 .openapi-ts-request.ts, openapi-ts-request.config.cjs 等格式，参考 cosmiconfig

import { defineConfig } from 'openapi-ts-request';

export default defineConfig({
  schemaPath: 'http://petstore.swagger.io/v2/swagger.json',
  serversPath: './src/apis',
});

支持传入数组配置进行生成

import { defineConfig } from 'openapi-ts-request';

export default defineConfig([
  {
    schemaPath: 'http://app.swagger.io/v2/swagger.json',
    serversPath: './src/apis/app',
  },
  {
    schemaPath: 'http://auth.swagger.io/v2/swagger.json',
    serversPath: './src/apis/auth',
  },
]);

在 package.json 的 script 中添加命令: "openapi": "openapi-ts",

运行：

npm run openapi

生成的接口：

src/apis/index.ts #接口入口文件
src/apis/types.ts #类型定义文件
src/apis/pet.ts #接口文件

// src/apis/pet.ts
/* eslint-disable */
// @ts-ignore
import request from 'axios';

import * as API from './types';

/** Update an existing pet PUT /pet */
export async function updatePet({
  body,
  options,
}: {
  body: API.Pet;
  options?: { [key: string]: unknown };
}) {
  return request<unknown>(`/pet`, {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
    },
    data: body,
    ...(options || {}),
  });
}

// ... 其他接口

JS

任意目录 xxx/xxx 新建 openapi-ts-request.config.js

const { generateService } = require('openapi-ts-request');

generateService({
  schemaPath: 'http://petstore.swagger.io/v2/swagger.json',
  serversPath: './apis',
});

在 package.json 的 script 中添加命令: "openapi": "node xxx/xxx/openapi-ts-request.config.js"

运行：

npm run openapi

TS

任意目录 xxx/xxx 新建 openapi-ts-request.config.ts

const { generateService } = require('openapi-ts-request');

generateService({
  schemaPath: 'http://petstore.swagger.io/v2/swagger.json',
  serversPath: './apis',
});

在 package.json 的 script 中添加命令: "openapi": "ts-node xxx/xxx/openapi-ts-request.config.ts",

运行：

npm run openapi

NPX

# npm
npx --package=openapi-ts-request -- openapi -i ./openapi.json -o ./apis
npx --package=openapi-ts-request -- openapi -i https://petstore3.swagger.io/api/v3/openapi.json -o ./apis

# pnpm
pnpm --package=openapi-ts-request@latest dlx openapi -i ./openapi.json -o ./apis
pnpm --package=openapi-ts-request@latest dlx openapi -i https://petstore3.swagger.io/api/v3/openapi.json -o ./apis

CLI

npm i openapi-ts-request -g

$ openapi --help

  Usage: openapi [options]

  Options:
    -V, --version                       output the version number
    -i, --input <string>                OpenAPI specification, can be a path, url
    -o, --output <string>               output directory
    -cfn, --configFileName <string>     config file name
    -cfp, --configFilePath <string>     config file path
    --requestLibPath <string>           custom request lib path, for example: "@/request", "node-fetch" (default: "axios")
    -f, --full <boolean>                full replacement (default: true)
    --enableLogging <boolean>           open the log (default: false)
    --priorityRule <string>             priority rule, include/exclude/both (default: "include")
    --filterCaseInsensitive <boolean>   whether to perform a case-insensitive match with includeTags, includePaths, excludeTags, excludePaths filters (default: false)
    --includeTags <(string|RegExp)[]>   generate code from include tags
    --includePaths <(string|RegExp)[]>  generate code from include paths
    --excludeTags <(string|RegExp)[]>   generate code from exclude tags
    --excludePaths <(string|RegExp)[]>  generate code from exclude paths
    --requestOptionsType <string>       custom request method options parameter type (default: "{ [key: string]: unknown }")
    --requestImportStatement <string>   custom request import statement, for example: "const request = require('@/request')"
    --apiPrefix <string>                custom the prefix of the api path, for example: "api"(variable), "'api'"(string)
    --isGenReactQuery <boolean>         generate react-query (default: false)
    --reactQueryMode <string>           react-query mode, react/vue (default: "react")
    --isGenJavaScript <boolean>         generate JavaScript (default: false)
    --isDisplayTypeLabel <boolean>      generate label matching type field (default: false)
    --isGenJsonSchemas <boolean>        generate JSON Schemas (default: false)
    --mockFolder <string>               mock file path, for example: './mocks'
    --authorization <string>            docs authorization
    --nullable <boolean>                null instead of optional (default: false)
    --isTranslateToEnglishTag <boolean> translate chinese tag name to english tag name (default: false)
    --isOnlyGenTypeScriptType <boolean> only generate typescript type (default: false)
    --isCamelCase <boolean>             camelCase naming of controller files and request client (default: true)
    --isSupportParseEnumDesc <boolean>  parse enum description to generate enum label (default: false)
    -h, --help                          display help for command

运行：

openapi --i ./spec.json --o ./apis

参数

属性	必填	类型	默认值	说明
schemaPath	是	string	-	Swagger2/OpenAPI3 地址
serversPath	否	string	'./src/apis'	运行结果文件夹路径
requestLibPath	否	string	'axios'	自定义请求方法路径，例如：'@/request'、'node-fetch'
full	否	boolean	true	是否全量替换
describe	否	string	-	描述信息，在用 cli 可交互运行方式时会用到
enableLogging	否	boolean	false	是否开启日志
priorityRule	否	string	'include'	模式规则，可选include/exclude/both
filterCaseInsensitive	否	boolean	false	执行 includeTags、includePaths、excludeTags、excludePaths 过滤时是否忽略大小写
includeTags	否	(string|RegExp)[]	-	根据指定的 tags 生成代码, priorityRule=include则必填
includePaths	否	(string|RegExp)[]	-	根据指定的 paths 生成代码
excludeTags	否	(string|RegExp)[]	-	根据指定的 tags 不生成代码
excludePaths	否	(string|RegExp)[]	-	根据指定的 paths 不生成代码
requestOptionsType	否	string	'{ [key: string]: unknown }'	自定义请求方法 options 参数类型
requestImportStatement	否	string	-	自定义请求方法表达式，例如："const request = require('@/request')"
apiPrefix	否	string	-	api path的前缀，例如：'api'(动态变量), "'api'"(字符串)
isGenReactQuery	否	boolean	false	是否生成 react-query
reactQueryMode	否	string	'react'	react-query 模式，可选 react/vue
isGenJavaScript	否	boolean	false	是否生成 JavaScript
isDisplayTypeLabel	否	boolean	false	是否生成 type 对应的label
isGenJsonSchemas	否	boolean	false	是否生成 JSON Schemas
mockFolder	否	string	-	mock文件路径，例如：'./mocks'
authorization	否	string	-	文档权限凭证
apifoxConfig	否	Apifox Config	-	apifox 配置
nullable	否	boolean	false	使用 null 代替可选
isTranslateToEnglishTag	否	boolean	false	将中文 tag 名称翻译成英文 tag 名称
isOnlyGenTypeScriptType	否	boolean	false	仅生成 typescript 类型
isCamelCase	否	boolean	true	小驼峰命名文件和请求函数
isSupportParseEnumDesc	否	boolean	false	解析枚举描述生成枚举标签，格式参考：系统用户角色:User(普通用户)=0,Agent(经纪人)=1,Admin(管理员)=2
binaryMediaTypes	否	string[]	-	自定义二进制媒体类型列表，默认包含：['application/octet-stream', 'application/pdf', 'image/', 'video/', 'audio/*']
hook	否	Custom Hook	-	自定义 hook

自定义 Hook

属性	类型	说明
afterOpenApiDataInited	(openAPIData: OpenAPIObject) => OpenAPIObject	自定义 OpenAPI 数据
customFunctionName	(data: APIDataType) => string	自定义请求方法函数名称
customTypeName	(data: APIDataType) => string	自定义类型名称
customClassName	(tagName: string) => string	自定义标签名
customType	({ schemaObject: SchemaObject | ReferenceObject, namespace: string, originGetType:(schemaObject: SchemaObject | ReferenceObject, namespace: string, schemas?: ComponentsObject['schemas']) => string, schemas?: ComponentsObject['schemas'], }) => string	自定义类型 返回非字符串将使用默认方法获取type
customFileNames	( operationObject: OperationObject, apiPath: string, apiMethod: string, ) => string[]	自定义生成的请求客户端文件名称，可以返回多个文件名称的数组(表示生成多个文件). 返回为空，则使用默认的方法获取
customTemplates	{ [TypescriptFileType.serviceController]?: <T, U>(item: T, context: U) => string; }	自定义模板，详情请看源码
customRenderTemplateData	{ [TypescriptFileType]?: (list: any[], context: {fileName: string, params: Record<string, unknown>}) => any[] }	自定义文件生成时的 list 参数处理，支持对不同文件类型进行精细化控制

hooks 示例

Apifox-Config

属性	类型	说明	必填
projectId	string	项目id	true
apifoxToken	string	获取	true
local	string	语言(默认: zh-CN)	false
apifoxVersion	string	默认: 2024-03-28, 获取当前版本	false
selectedTags	* 或 string[]	默认: *	false
excludedByTags	string[]	默认: []	false
oasVersion	string	指定用于导出的 OpenAPI 规范的版本，可以有值如 "2.0"、"3.0"、"3.1"	'3.0'
exportFormat	string	指定导出的 OpenAPI 文件的格式，可以有值如 'JSON' 或 'YAML'	'JSON'
includeApifoxExtensionProperties	boolean	指定是否包含 Apifox 的 OpenAPI 规范扩展字段 x-apifox	false
addFoldersToTags	boolean	指定是否在标签字段中包含接口的目录名称	false

JSON Schemas

• 默认生成 components.schemas 下面的 JSON Schemas，paths 对应的 JSON Schemas 目前需自行解析
• 提供一个解析 schema 的函数，用于将 $ref，$allOf 的引用填充到 当前schema

export declare function patchSchema<T extends object>(
  schema: ISchemaObject,
  schemas: ComponentsObject['schemas']
): T;

Mock

目前使用 mockjs 生成 mock 数据，mocks 文件启动需要借助 @umijs/server，后面会寻找其他方案以达到更好的 mock 体验

适配uniapp

适配 uniapp 推荐采用自定义 request 函数的方式，你也可以使用 @uni-helper/axios-adapter 适配器，详情见 【使用手册 2.2】

旧版本升级注意事项

• 当前命名规范修改
• 当前版本已完成增量修改, 不会影响以前
• 可以弃用openapi-ts命令, 直接使用openapi

沿用旧版本命名规范配置如下

import type { APIDataType } from 'openapi-ts-request/dist/generator/type';
import {
  genDefaultFunctionName,
  resolveFunctionName,
  stripDot,
} from 'openapi-ts-request/dist/generator/util';

export default {
  hook: {
    customFunctionName(data: APIDataType, prefix: string) {
      if (data.operationId)
        return resolveFunctionName(stripDot(data.operationId), data.method);
      return data.method + genDefaultFunctionName(data.path, prefix);
    },
  },
};

贡献

环境要求

• node 18+
• pnpm 9+

提交 Pull Request

1. 熟悉 Pull Request 规范
2. fork 此仓库
3. 开一个新分支修改代码：git checkout -b my-branch main
4. 确保你的代码可以通过所有测试用例(新增功能需要添加新的功能测试用例)：pnpm test:unit
5. 创建 changeset 文件通过命令：pnpm changeset
6. 使用 commit 提交你的修改(需遵循 commitlint 规范)
7. 如果涉及文档，请同步更新 README.md、READMD-en_US.md、agents.md
8. 发起 Pull Request

感谢

• openapi2typescript