使用Orval自动生成前端TypeScript接口文档

先决条件：

后端使用swagger接口文档，即可以打开一个接口文档的网页，内容全是JSON文本的网页。原理其实很简单就是用脚本读取这个网页的JSON数据，然后转换为前端的TypeScript文档。
前端必须使用TypeScript，其实TypeScript不难，学了之后前端开发会变简单。

安装使用教学：

先使用你熟悉的包管理器安装Orval：

npm i orval -D

yarn add orval -D

pnpm add orval -D

安装完毕之后在前端的根路径下创建一个 orval.config.ts的配置文件，我这里给个模版：

import { defineConfig } from 'orval'

export default defineConfig({
  petstore: {
    input: {
      target: 'http://127.0.0.1:8088/api/v3/api-docs/default', // openapi 文档地址
    },
    output: {
      target: 'src/api-client/index.ts', // 生成请求函数
      schemas: 'src/api-client/models', // 生成的类型文件
      workspace: 'src/api-client', // 基础目录
      mode: 'tags-split', // 按 tags 拆分文件
      client: 'axios', // 使用 axios 作为请求库
      clean: true, // 每次生成前清空目录
      mock: false, // 是否生成 mock
      override: {
        mutator: {
          path: '../axios-instance.ts', // 自定义 axios 实例（相对 workspace）
          name: 'axiosInstance',
        },
      },
    },
    hooks: {
      afterAllFilesWrite: 'prettier --write ',
    },
  },
})

具体的配置可以参考官网：Orval官网

这里注意一下 mutator的配置，他可以自定义你请求实例的配置，这也是我选择它的缘故：

然后在src目录下创建一个Axios实例的配置文件，我这里也给出参考，可以自行根据需求修改：

import axios, { type AxiosInstance, type AxiosRequestConfig } from 'axios'

// 复用的 Axios 实例
const instance: AxiosInstance = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL,
  timeout: 5000,
})

// 请求拦截器
instance.interceptors.request.use(
  (config) => {
    return config
  },
  (error) => {
    return Promise.reject(error)
  },
)

// 响应拦截器（统一返回 data）
instance.interceptors.response.use(
  (response) => {
    return response.data
  },
  (error) => {
    return Promise.reject(error)
  },
)

// Orval mutator 期望的签名：axiosInstance<T>(config) => Promise<T>
export const axiosInstance = async <T = unknown>(config: AxiosRequestConfig): Promise<T> => {
  const response = await instance.request<T>(config)
  // 上面的响应拦截器已将返回值转为 data，这里为了类型安全再断言一次
  return response as unknown as T
}

注意我的 BaseUrl使用了Vite的一个配置文件，他可以动态的解析，生成环境的和开发环境两个的 BaseUrl不同。这里不细说了。

自此我们基本配置就完成了。然后去 package.json里添加一个脚本，方便使用：

"gen:api:orval": "orval --config orval.config.ts"

运行之后就可以在 src/api-client下面看到生成的配置文件：

这里注意一下，后端 Controller接口上的Tag标签不能用中文，用中文这里生成也是中文。。。