使用 openapi-generator 自动生成 typescript + axios 文件

Oct 6, 2023·3 min
AI 生成的摘要
在前端开发中，处理大量接口对接是一项繁琐的工作。本文介绍了一种通过OpenAPI规范自动生成接口文件的方法，使用openapi-generator工具可以根据OpenAPI规范的JSON文件生成TypeScript+Axios的API文件，从而简化前端接口对接的工作。文章详细说明了如何安装和使用openapi-generator-cli，并展示了生成文件的命令和项目中的实际应用示例。

在前端开发时候，总是会有许多的接口需要你去对接。

如果手动去添加一些接口，那会有许多的工作量，这些工作都是重复且无趣的。

我目前开发的一个项目，关接口就有 200+，所以我想着如何去有效简化重复的工作。

在一番搜索下，找到了一个不错的方案。通过一个 openapi 规范的接口 JSON 去自动生成接口文件，并在前端调用。

OPENAPI 是什么？

注意是OpenAPI 不是OPENAI。他是一个标准，定义了 API 的结构、参数、返回值、描述等信息。

后端常用的自动化生成接口文档工具,例如 Swagger，就会生成一个通用的，符合 openapi 标准的接口文档以及文件。

你可以找你的后端同学，让他发你一个接口说明的 json 格式文件，就可以用它来实现自动生成 typescript+axios 的 api 文件。

如何生成？

openapi-generator

它可以根据 OpenAPI 规范（支持 2.0 和 3.0）自动生成 API 客户端库。

但是他是一个 java 项目，如果我们要使用，就需要拥有 java 环境，并且下载这个工具的 jar 才可以运行。

所以我们可以使用 openapi-generator-cli 来简化下载 jar 的这个操作(java 环境还是要有的,要求是 JAVA 11+)。

npm 安装 openapi-generator-cli

npm install -g @openapitools/openapi-generator-cli

假设我们的接口文档地址是http://192.168.1.66:8080/openapi.json

我们把生成的 api,放到前端根目录的./src/api/generated

生成typescript文件，网络请求库使用axios

就可以输入以下命令去生成文件。

openapi-generator-cli generate -i http://192.168.1.66:8080/openapi.json -g typescript-axios --additional-properties=apiPackage=api,modelPackage=model,withSeparateModelsAndApi=true -o ./src/api/generated --skip-validate-spec

生成的文件结构如下: 生成的文件结构

在src/api目录下，创建 index.ts

import { DefaultApi } from './generated'

// 这里用的是vite来创建项目
// 从环境配置里获取url
const envUrl = `${import.meta.env.VITE_BASE_URL}`

export const api = new DefaultApi({
  basePath: envUrl,
  isJsonMime(mime) {
    return mime === 'application/json'
  },
})

这样就实现了自动化生成接口文档，并且可以配置对应的 token 和请求路径。其实他还支持挺多参数配置，这里只是一个例子。

项目使用 Eg:

app.tsx
import { useEffect } from 'react'

function App() {
  useEffect(() => {
    api.GetUserDetail()
  }, [])
  return <div>Hello world!</div>
}

图方便，还可以添加到 package.json 里

 "scripts": {
    "gen:api": "openapi-generator-cli generate -i http://192.168.1.66:8080/openapi.json -g typescript-axios --additional-properties=apiPackage=api,modelPackage=model,withSeparateModelsAndApi=true -o ./src/api/generated --skip-validate-spec"
  },

相关链接

cd ..