vite-plugin-auto-generate-api

该插件是基于 swagger-typescript-api 工具优化后根据后端 swagger 文档自动生成前端接口工具，主要支持以下功能：

功能 🦖

1.1.*

• 自定义接口类型或名称
• 支持配置接口字段是否必选
• 支持配置请求取消
• 支持配置数据模拟
• 支持静默错误通知
• 判断 swagger 文档是否更新，并自动生成版本注释

1.2.*

• 支持根据模块划分接口

使用方法 🦕

安装

1# npm
2npm install vite-plugin-auto-generate-api
3
4# pnpm
5pnpm install vite-plugin-auto-generate-api

配置

文件结构约定

1. 单个模块

api/
│
├── modules/
│   └── xxx.ts
├── index.ts
└── option.ts

2. 多个模块

api/
├── module1/
│   ├── modules/
│   │   └── xxx.ts
│   ├── index.ts
│   └── option.ts
│
└── module2/
    ├── modules/
    │   └── xxx.ts
    ├── index.ts
    └── option.ts

配置项

1// vite.config.js
2
3import AutoGenerateApi from "vite-plugin-auto-generate-api"
4// 该文件具体内容请看使用说明
5import { blobResponseTypeNames, formatModuleNames, formatRouteNames, ignoreModuleNames, fixTypes, requiredTypes } from './fixed'
6...
7export default defineConfig({
8    ...others,
9    plugins: [
10        // 单个模块的情况
11        AutoGenerateApi([{
12            // 必填项
13            url: "",
14            outputDir: "src/api/modules" // 相对于项目根路径
15            // 用于身份验证（可选）
16            username: "",
17            password: "",
18            // 自定义接口基础路径 默认为"./" + env.V_API_BASE
19            baseUrl: "./api"
20            // 其他配置项（可选）
21            blobResponseTypeNames,
22            formatModuleNames,
23            formatRouteNames,
24            ignoreModuleNames,
25            fixTypes,
26            requiredTypes
27        }])
28        // 单个模块的情况
29        AutoGenerateApi([{
30            // 必填项
31            url: "",
32            outputDir: "src/api/module1/modules" // 相对于项目根路径
33            // 自定义接口基础路径 默认为"./" + env.V_API_BASE
34            baseUrl: "./api/module1"
35            // 其他配置项
36            // ...
37        },{
38            // 必填项
39            url: "",
40            outputDir: "src/api/module2/modules" // 相对于项目根路径
41            // 自定义接口基础路径 默认为"./" + env.V_API_BASE
42            baseUrl: "./api/module2"
43            // 其他配置项
44            // ...
45        }])
46    ]
47})
48

使用说明

1、接口错误修正或名称修正 ---- fixed.ts (文件名可以自定义)

1/**
2 * 说明：此数组表示哪些请求返回的是文件流形式
3 * 具体对应swagger上的中文名称 或者 api方法注释中的 @summary “中文名称”
4 */
5export const blobResponseTypeNames = ["历史数据导出", "图片下载"];
6
7/**
8 * 说明：此对象是对自动生成的后端接口文件重命名
9 * 格式如下：
10 * 模块名称：'重命名名称'
11 *
12 * 模块名称：对应swagger请求路径中 `/模块名称/aaaa` 或 `/模块名称` 中的模块名称字段
13 * 或者 对应api方法注释中 @request POST:/模块名称/history-export
14 */
15export const formatModuleNames = {
16  monitor: "history",
17  record: "system",
18};
19
20/**
21 * 说明：此对象是对自动生成的后端接口请求方法重命名
22 * 格式如下：
23 * {
24 *     "moduleName": {
25 *          "原方法名称"：'重命名名称'
26 *      }
27 * }
28 *
29 * moduleName：api文件的文件名的小写
30 * 原方法名称：api文件中的方法名称
31 */
32export const formatRouteNames = {
33  history: {
34    historyExport: "exportRecord",
35  },
36};
37
38/**
39 * 说明：此数组是对与业务无关的接口进行屏蔽
40 *
41 * 对应swagger请求路径中 /模块名称/aaaa 或 /模块名称 中的模块名称字段
42 * 若已生成，需要手动删除项目中的文件
43 */
44export const ignoreModuleNames = ["healthz"];
45
46/**
47 * 说明：此对象是对后端接口定义修正
48 * {
49 *     类型名称: {
50 *          字段名称：具体类型
51 *      }
52 * }
53 *
54 * 类型名称：对应 Types.ts 文件中 export interface RoleCommandType {}, RoleCommandType 去掉Type后的名称
55 * 字段名称：对应 Types.ts 文件类型中的具体字段
56 * 具体类型格式如下：
57 * { type: 'string' }
58 * { type: 'number' }
59 * { type: 'boolean' }
60 * { type: 'array', items: { type: 'string' } }
61 * ...
62 */
63export const fixTypes = {
64  RoleVo: {
65    authority: { type: "array", items: { type: "string" } },
66  },
67  RoleCommand: {
68    authority: { type: "array", items: { type: "string" } },
69  },
70  AccountVo: {
71    authority: { type: "array", items: { type: "string" } },
72    accountList: { type: "array", items: { type: "string" } },
73  },
74};
75
76/**
77 * 说明：此对象是对后端接口自定义必选字段
78 * 格式如下：
79 * 类型名称：['字段名称']
80 * ...
81 */
82export const requiredTypes = {
83  AccountCommand: ["password"],
84};

2、发起请求

1// 基本请求 params 为请求参数。option为配置项，下面会列出常用的
2const data = await historyApi.getCondition(params, option);

3、数据模拟

1// 前提配置环境变量文件和vite配置文件
2// "V_MOCK_BASE": "mock",
3// '/mock': {
4//     target: 'http://127.0.0.1:4523/m1/5761631-5445089-default/',  // 此处填写mock服务地址
5//     rewrite: path => path.replace(/^\/mock/, '')
6// }
7
8// 第一种方式，直接在使用的地方设置mock配置项为true
9const data = await historyApi.getCondition(params, {
10  mock: true,
11});
12
13// 第二种方式在api/options.ts文件中修改
14export const options = {
15  History: {
16    getCondition: {
17      mock: true,
18    },
19  },
20};

4、禁用接口错误信息提示

1// 第一种方式，直接在使用的地方设置silent配置项为true
2const data = await historyApi.getCondition(params, {
3  silent: true,
4});
5
6// 第二种方式在api/options.ts文件中修改
7export const options = {
8  History: {
9    getCondition: {
10      silent: true,
11    },
12  },
13};

5、接口取消请求

1// 第一种方式，直接在使用的地方设置cancel配置项为true
2const data = await historyApi.getCondition(params, {
3  cancel: true,
4});
5
6// 第二种方式在api/options.ts文件中修改
7export const options = {
8  History: {
9    getCondition: {
10      cancel: true,
11    },
12  },
13};
14
15// 取消方式
16historyApi.cancel("getCondition");

License

Made with ruhangs

Published under MIT License.