使用 OpenAPI Generator 生成客户端代码

介绍

OpenAPI Generator 是一个开源的代码生成工具，用于从 OpenAPI 规范（如 Swagger）生成客户端代码、服务器代码、文档和配置。

在此之前，我在服务端根据代码输出了 OpenAPI 和 Swagger 文档，Goframe 提供了开箱即用的集成：

1
2
3
4
5
# manifest/config/config.yaml
server:
  address: ":8080"
  openapiPath: "/api.json"
  swaggerPath: "/swagger"

接着，我的目标是通过 OpenAPI Generator 生成客户端的前端代码。

最终生成的结果大致如下：

Files

调用的代码如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import { Configuration, EmailApi } from "@/api";

const emailApi = new EmailApi(
  new Configuration({ basePath: import.meta.env.VITE_API_BASE_URL }),
);

const sendVerifCode = async () => {
  try {
    const res = await emailApi.apiLoginEmailVerifCodePost({
      email: "xxx@outlook.com",
    });
    console.debug(res);
  } catch (error) {
    console.error(error);
  }
};

安装

OpenAPI Generator 提供了许多的安装方式，从中任意选择一种即可：

OpenAPI Generator 安装文档

生成客户端代码

客户端的编程语言使用 typescript，使用 axios 库来发送请求，可以选择 OpenAPI Generator 提供的一个官方模版 typescript-axios，其他的可选模版见：Generators。

1
2
3
4
openapi-generator generate \
-i http://127.0.0.1:8080/api.json \
-g typescript-axios \
-o src/api

如果你看了 typescript-axios 的文档，里面还列出了一些可以配置的选项，可以在运行命令的时候添加 --additional-properties 修改：

1
2
3
4
5
openapi-generator generate \
-i http://127.0.0.1:8080/api.json \
-g typescript-axios \
-o src/api
--additional-properties npmName=api,npmVersion=0.1.0

如果需要修改的数量比较多，还可使用配置文件，新建一个 openapi-generator-config.yaml 文件：

1
2
npmName: api
npmVersion: 0.1.0

然后运行命令：

1
2
3
4
5
openapi-generator generate \
-i http://127.0.0.1:8080/api.json \
-g typescript-axios \
-o src/api
-c ./openapi-generator-config.yaml

配置 axios 的 baseURL

这个生成的代码里面没有配置 axios 的 baseURL，导致我一直请求不懂，在文件 base.ts 里面：

1
export const BASE_PATH = "http://localhost".replace(/\/+$/, "");

我尝试了一下，这个地方的运行结果似乎没办法修改，换一个思路，在使用的时候修改吧，好在它提供了一个 Configuration 接口：

1
2
3
4
5
import { Configuration, EmailApi } from "@/api";

const emailApi = new EmailApi(
  new Configuration({ basePath: import.meta.env.VITE_API_BASE_URL }),
);

这里使用的是 VITE 的环境变量来提供 API 的地址，可根据自己的情况修改。

尝试一下调用：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
const sendVerifCode = async () => {
  try {
    const res = await emailApi.apiLoginEmailVerifCodePost({
      email: "xxx@outlook.com",
    });
    console.debug(res);
  } catch (error) {
    console.error(error);
  }
};

大功告成。