Skip to content

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

🕒 发布时间: 🕒 阅读时间: 0 分钟✍︎ 文章字数: 0

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

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

我目前开发的一个项目,关接口就有 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

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

假设我们的接口文档地址是http://192.168.1.66:8080/openapi.json
我们把生成的 api,放到前端根目录的./src/api/generated
生成typescript文件,网络请求库使用axios
就可以输入以下命令去生成文件。

bash
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

typescript
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:

typescript
import { useEffect } from "react";

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

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

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"
  },

相关链接

Last updated: