React项目中使用openapi-typescript-codegen自动生成API客户端

作者：青柠时间：2026-10-31 17:00:55浏览：412

本文介绍openapi-typescript-codegen工具，该工具根据OpenAPI规范自动生成TypeScript类型定义和API客户端代码。通过配置input、output及client参数，可快速生成与axios等库兼容的请求代码，支持自定义request.ts文件以复用拦截器，确保前后端接口同步且类型安全，显著提升React项目中的开发效率。

本文深入介绍openapi-typescript-codegen这一工具，它能协助开发者快速生成TypeScript代码，使API请求具备更高的效率与类型安全性，从而让开发者从手动编写冗长的请求代码中解脱出来，将精力集中于业务逻辑的实现。下文将详细解析其功能与使用技巧，旨在优化开发体验。

openapi-typescript-codegen工具概述

openapi-typescript-codegen是一款基于OpenAPI规范自动生成TS代码的开源工具。OpenAPI作为广泛采用的API规范，详细描述了RESTful API的结构与行为，涵盖请求、响应及数据模型等要素。该工具利用OpenAPI规范，自动化生成匹配的TS类型定义与API客户端代码。前端开发者无需再根据后端接口手动编写接口函数，只需一键即可生成，大幅提升了编程效率。

如需查阅该开源工具的源码，可访问官网获取，此处不再赘述。下文将对这一开源工具进行简要介绍。

openapi-typescript-codegen的主要作用包括以下几个方面：

1）自动生成TS类型：通过读取OpenAPI规范文件，生成对应的TS类型定义。开发者可直接在代码中使用这些类型，无需手动编写类型声明，从而确保类型安全。

2）生成API客户端代码：自动生成与API交互的客户端代码，包括请求函数、错误处理逻辑以及请求参数的类型化定义。

3）简化API集成：帮助快速生成与API交互所需的全部代码，避免手动构建请求、解析响应等繁琐工作，从而提高开发效率。

4）保持与API规范同步：通过直接从OpenAPI规范生成代码，确保每次API更新时，相关的客户端代码能自动同步，避免了手动更新可能带来的繁琐与遗漏。

根据官方文档介绍，使用该开源工具的优势主要体现在以下几点：

openapi-typescript-codegen工具概述

总体而言，这是一个非常有价值的工具，特别适用于需要频繁与第三方或内部API交互的TS项目。它帮助开发者减少了手动编写重复代码的工作量，确保了代码的类型安全与可靠性，同时能与API文档保持同步，减少了开发中的错误与不一致问题。具体细节可查阅官网，此处不再赘述。

openapi-typescript-codegen工具概述

借助该工具，开发者不仅能提高开发效率，还能享受更加流畅和高效的工作体验。接下来将讲解该开源工具的具体使用方法，不足之处敬请谅解。

核心命令与参数配置

下文介绍如何快速上手openapi-typescript-codegen，帮助开发者在项目中轻松生成与API交互所需的代码，提升开发效率并确保类型安全。官方文档提供了该工具使用的一些核心命令，如下所示：

$ 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, tab] (default: "4")
    --postfixServices         Service name postfix (default: "Service")
    --postfixModels           Model name postfix
    --request <value>         Path to custom request file
    -h, --help                display help for command
  Examples
    $ openapi --input ./spec.json --output ./generated
    $ openapi --input ./spec.json --output ./generated --client xhr

从上述核心命令的示例中可以看出，该工具主要使用这两个常用命令，此处对其做简要介绍：

例如：openapi --input ./spec.json --output ./generated --client xhr

1）–input：指定接口文档的路径、URL或字符串内容（必填项）。

2）–output：指定代码生成的目录。

3）–client：指定生成的代码所使用的请求库。

请求库集成与安装

作为前端开发者最常用的请求库，axios是首选。在终端执行以下命令进行安装：

// 首先下载axios
npm install axios
// 然后安装成功API工具
npm install openapi-typescript-codegen --save-dev

生成命令：配置完成后，我们可以在demo项目中测试一下。在项目终端执行上述命令时，控制台可能会报错无法识别，情况如下：

openapi --input 你的在线swagger.json地址 --output ./src/api --client axios

openapi-typescript-codegen工具概述

代码生成与问题解决

解决该问题有两种方法：一是将开源工具全局安装，二是使用npx临时安装，两种方式均可：

// 全局安装
npm install openapi-typescript-codegen -g
// 临时安装
npx openapi-typescript-codegen --input 你的在线swagger.json地址 --output ./src/api--client axios

如下所示，我们根据在线的swagger.json直接生成了API接口代码：

openapi-typescript-codegen工具概述

为了方便后期重新生成最新的接口代码，可以将命令放置在package.json文件中，通过执行npm命令快速生成接口代码，如下所示：

openapi-typescript-codegen工具概述

生成目录结构与自定义请求

目录介绍：接下来对上面生成的api目录下的文件代码进行简要介绍：

1）core：包含接口请求类型限制、接口请求基本设置以及封装的接口请求request函数。

2）models：包含接口请求函数中的所有TS类型。

3）services：包含所有的请求接口函数。

4）index.ts：所有请求函数的出口文件。

我们可以自定义一个request.ts文件，然后执行以下命令，在每次重新生成的api文件中，复制并使用我们自定义的request.ts文件：

// axios基础封装
import axios from 'axios'
export const request: any = axios.create({
    baseURL: '服务器接口根地址',
    timeout: 5000,
})
// 请求拦截器
request.interceptors.request.use((config: any) => {
    // 请求拦截器
    return config
}, (error: any) => {
    return Promise.reject(error)
})
// 响应拦截器
request.interceptors.response.use((res: any) => {
    return res.data
},  (error: any) => {
        //处理网络错误
        let msg = ''
        const status = error.response.status
        switch (status) {
            case 401:
                msg = 'token过期'
                break
            case 403:
                msg = '无权访问'
                break
            case 404:
                msg = '请求地址错误'
                break
            case 500:
                msg = '服务器出现问题'
                break
            default:
                msg = '网络出现问题'
                break
        }
        return Promise.reject(error)
    }
)

在生成的代码中执行以下命令，该--request参数告诉生成器不要生成默认的request.ts文件，而是复制指定的自定义文件进行使用：

openapi --input swagger地址 --output ./src/api --request ./src/utils/request.ts --client axios

随意调用一个函数：

import { Button } from 'antd';
import { BasicDataService } from './api'
const App = () => {
  const getData = async () => {
    const data = await BasicDataService.basicDataQueryLocation()
    console.log(data)
  }
  getData()
  return (
    <div style={{ display: 'flex', gap: '20px' }}>
      <Button type='primary'>按钮</Button>
    </div>
  )
}
export default App

结果被打印了出来：

openapi-typescript-codegen工具概述