当前位置：首页 > news >正文

React--》掌握openapi-typescript-codegen快速生成API客户端代码

news 2024/11/14 17:57:13

今天深入探索一个神奇的工具——openapi-typescript-codegen。它不仅能够帮助你快速生成TS代码，还能让你的API请求更加高效、类型安全，让开发者摆脱手动编写冗长请求代码的困扰，专注于实现业务逻辑。接下来让我们一起来了解它的强大功能和使用技巧，提升你的开发体验！

openapi-typescript-codegen：根据OpenAPI规范自动生成TS代码的开源工具，OpenAPI 是一种广泛使用的API规范，能够描述RESTful API的结构和行为，包括请求、响应、数据模型等内容，而openapi-typescript-codegen这个工具正是利用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 --helpUsage: 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 commandExamples$ openapi --input ./spec.json --output ./generated$ openapi --input ./spec.json --output ./generated --client xhr

从上面核心命令举出的examples我们可以知道，该工具主要使用的就是这两个常用命令，这里对其做一个简单的介绍：

例如：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.statusswitch (status) {case 401:msg = 'token过期'breakcase 403:msg = '无权访问'breakcase 404:msg = '请求地址错误'breakcase 500:msg = '服务器出现问题'breakdefault: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

结果被打印了出来：