openapi-typescript-cli：优雅的 OpenAPI 到 TypeScript 请求层代码生成工具

作者：一缘（zhuty.com）

一、工具背景与设计初衷

在前后端分离开发模式下，接口文档与前端请求层代码的同步维护一直是痛点。openapi-typescript-cli 旨在通过一行命令，将 OpenAPI/Swagger 文档自动生成类型安全、可维护的 TypeScript 请求层代码，极大提升开发效率与协作体验。

• 支持 OpenAPI v3、Swagger、FastAPI 等主流接口文档
• 自动生成接口类型定义（.d.ts）与请求方法（.ts）
• 兼容多种接口风格，支持自定义中间件
• 生成代码基于 Axios，易于二次封装

项目主页 @npmjs.com

二、主要功能与特性

• 一键生成 TypeScript 类型和请求方法，接口变更自动同步
• 支持本地 JSON 文件和远程 OpenAPI 文档 URL
• 支持自定义中间件，灵活命名模块名和方法名
• 兼容 query/body 混合参数、Header 定制等复杂场景
• 生成代码不会覆盖已有自定义 request.js/middleware.js
• 适合团队协作、前后端接口规范统一

三、安装与使用方法

1. 安装

npm i -g openapi-typescript-cli
# 或用 npx 临时运行
npx openapi-typescript-cli -h

2. 基本用法

• 从本地 OpenAPI JSON 文件生成：

openapi-typescript-cli -f path/to/openapi.json -n api

• 从远程 OpenAPI 文档 URL 生成：

openapi-typescript-cli -u http://localhost:8008/openapi.json -n api

• 使用自定义中间件：

openapi-typescript-cli -u http://localhost:8008/openapi.json -m ./middleware.js

3. 生成结果

默认会在当前目录生成：

• api.d.ts：接口类型定义
• api.ts：接口请求方法
• request.js：Axios 封装（首次生成）
• middleware.example.js：中间件范例

推荐将 API 请求层单独放在 src/api 目录。

四、代码示例与业务集成

1. 生成的 TypeScript 请求方法

export let roleManage = {
  // 删除角色
  deleteRole: async (param: number[], opt: AxiosRequestConfig = {}): Promise<Type.ResponseBoolean> => await request({
    url: '/system/roleManage/deleteRole',
    method: 'post',
    data: param,
    ...opt,
  }),
}

2. 业务调用示例

import { roleManage } from '@/api/api';

<Button
  type="primary"
  onClick={async () => {
    let res = await roleManage.deleteRole([1, 2]);
    console.log(res);
  }}
>
  测试按钮
</Button>

五、中间件自定义命名

当后端接口命名不规范或需自定义模块/方法名时，可通过中间件灵活处理：

// middleware.js
module.exports = function ({operationId, description, path, method, tag}){
  return {
    moduleName: tag,
    functionName: operationId
  }
}

六、最佳实践与适用场景

• 前后端接口频繁变更、需自动同步类型和请求层
• 多人协作、接口命名需统一规范
• 适用于 FastAPI、SpringBoot、NestJS 等支持 OpenAPI 的后端
• 支持复杂参数、Header、鉴权等场景

七、与同类工具对比

八、常见问题与建议

• 建议接口文档遵循 OpenAPI v3 规范，便于自动化生成
• 生成代码后可结合团队实际二次封装 request.js
• 中间件可灵活适配各种后端命名风格
• 欢迎在 npm 页面 留言或提 Issue

九、结语

openapi-typescript-cli 致力于让前端 API 请求层开发更高效、规范、自动化。欢迎大家试用、反馈、共建更好的前后端协作体验！