本文介绍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更新时，相关的客户端代码能自动同步，避免了手动更新可能带来的繁琐与遗漏。
根据官方文档介绍，使用该开源工具的优势主要体现在以下几点：
总体而言，这是一个非常有价值的工具，特别适用于需要频繁与第三方或内部API交互的TS项目。它帮助开发者减少了手动编写重复代码的工作量，确保了代码的类型安全与可靠性，同时能与API文档保持同步，减少了开发中的错误与不一致问题。具体细节可查阅官网，此处不再赘述。
借助该工具，开发者不仅能提高开发效率，还能享受更加流畅和高效的工作体验。接下来将讲解该开源工具的具体使用方法，不足之处敬请谅解。
核心命令与参数配置
下文介绍如何快速上手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
代码生成与问题解决
解决该问题有两种方法：一是将开源工具全局安装，二是使用npx临时安装，两种方式均可：
// 全局安装
npm install openapi-typescript-codegen -g
// 临时安装
npx openapi-typescript-codegen --input 你的在线swagger.json地址 --output ./src/api--client axios如下所示，我们根据在线的swagger.json直接生成了API接口代码：
为了方便后期重新生成最新的接口代码，可以将命令放置在package.json文件中，通过执行npm命令快速生成接口代码，如下所示：
生成目录结构与自定义请求
目录介绍：接下来对上面生成的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结果被打印了出来：
到此这篇关于React掌握openapi-typescript-codegen快速生成API客户端代码的文章就介绍到这了，更多相关react openapi-typescript-codegen API内容请搜索本站以前的文章或继续浏览下面的相关文章，希望大家以后多多支持本站！