AutoAPIGen

Appearance

基本设置 ​

在使用 AutoAPIGen 插件前，您需要进行一些基础配置以满足不同项目的需求。以下是每项设置的详细说明：

1. 请求体解析依赖 ​

  • 默认依赖：qs
  • 作用：用于解析 json 格式的请求体。
  • 注意：确保您的项目已安装 qs 依赖。

2. 示例项目 ​

文档示例基于 apifox 平台上的公开项目 OpenAI 的接口文档进行说明。

3. 应用支持 ​

  • 当前仅支持 API 文档管理平台 apifox。
  • 后续会根据需求增加对 Postman 和 ApiPost 的支持。

4. 认证配置 ​

重要提示：最新版 Apifox 已改为使用 Cookie 进行认证，推荐使用 Cookie 方式。旧版本用户仍可使用 Authorization 方式。

插件支持两种认证方式，只需配置其中一种即可：

  • 用途：用于获取项目信息的认证凭证（最新版 Apifox 推荐方式）。
  • 获取方式：
    1. 登录网页版 Apifox。
    2. 按 F12 打开开发者工具。
    3. 在 Network 面板中选择任意请求，查看 Headers 选项卡，找到 Cookie 字段并复制其完整值。
  • 配置位置：将复制的 Cookie 值粘贴到插件的 Cookie 配置 输入框中。
  • 优势：最新版 Apifox 的标准认证方式，稳定性更好。

方式二：Authorization 认证（旧版本） ​

  • 用途：用于获取项目信息的 Token（旧版本 Apifox 使用）。
  • 获取方式：
    1. 登录网页版 Apifox。
    2. 按 F12 打开开发者工具。
    3. 在 Network 面板中选择任意请求，查看 Headers 选项卡，找到 Authorization 字段并复制其值。
  • 配置位置：将复制的 Authorization 值粘贴到插件的 Authorization 配置 输入框中。

注意事项 ​

  • 认证信息（Cookie 或 Authorization）未配置时，将无法获取项目和接口信息，也无法生成接口文档。
  • 认证信息具有时效性，如果认证失败，请重新获取最新的认证信息。
  • 推荐使用 Cookie 认证方式，这是 Apifox 最新版本的标准认证方式。

5. 生成路径 ​

  • 插件会自动读取当前工作空间的目录结构。
  • 您可以手动选择接口文件的生成位置，支持个性化目录布局。

6. 项目 ID 配置 ​

  • 配置 Cookie 或 Authorization 后，点击 获取项目列表 按钮。
  • 在下拉框中选择一个项目，即可获取项目 ID。
  • 左侧接口列表会显示该项目下的所有接口。

7. 接口模型 ​

支持以下三种接口模型：

1. axios 模型 ​

  • 自动生成适用于 axios 的接口请求代码。
  • 可结合 axios 引用路径 进行个性化配置。

2. 微信小程序 模型 ​

  • 生成基于 wx.request 的接口请求代码。
  • 首次生成时，自动在生成目录下创建以下文件：
    1. index.ts：封装 wx.request 方法（必需）。
    2. interface.d.ts：接口参数类型定义（可自定义）。
  1. env.config.ts：环境变量配置（可自定义）。
  • 注意：修改或删除 interface.d.ts 和 env.config.ts 后，需同步调整 index.ts 的引用。

3. 自定义 模型 ​

  • 提供高度灵活性，适用于复杂场景。
  • 可通过自定义函数控制生成的代码格式。
  • 支持自定义返回函数和拓展函数。

8. 使用项目名 ​

  • 开启后，生成的接口文件会在项目名目录下分组管理。
  • 适用于调用多个后台项目接口的场景，可有效避免不同项目接口冲突。

9. Axios 引用路径 ​

可以配置 axios 的引用路径，用于生成 axios 请求代码。若不配置，则默认使用用 import axios from 'axios'。可以基于自己的业务需求对 axios 进行二次封装。

eg: 配置 import http from '@/utils/http', 则在生成对应的接口请求时会使用 http 代替 axios。

axios返回数据key ​

  • 需要和后台约定，返回的数据使用统一的数据格式，例如：
json
{
    "code": 0,
    "data": {},
    "msg": ""
}
  • 在 axios 的二次封装中，默认只返回 data 字段的数据，在此处配置 data， 则最终生成的接口返回数据为 data 字段的数据，生成的接口定义中也只会有 data 部分的类型定义。也可返回多个字段，用英文逗号分隔。
  • 配置为空，则返回 完整的接口数据。

注：需要结合 axios 的二次封装的返回结果和规范的后台数据格式来配置。

prettier配置 ​

  • 作用：生成的接口文件将自动使用 prettier 格式化。
  • 插件支持：
    • 内置 prettier，默认使用了 prettier-plugin-sort-imports 和 prettier-plugin-organize-imports 这两个插件来做为基本的格式化规则。
    • 支持自定义 prettier 配置，可以配置 prettier 的其它规则。
  • 限制：暂不支持需要依赖第三方插件的 prettier 配置。
  • 注意：目前 cursor 编辑器内置格式化功能存在一些问题，会导致配置的 prettier 规则失效，但不影响生成接口文件，可以在生成接口文件后手动格式化或忽略。

自定义返回函数 ​

  • 作用：允许用户自定义生成的接口函数代码。
  • 语法：需要提供一个返回字符串的函数，该字符串将作为生成的接口函数代码。
  • 参数：函数接收一个 options 对象，包含接口相关信息。

自定义拓展函数 ​

  • 作用：允许用户在生成接口函数的同时，生成额外的辅助函数。
  • 语法：需要提供一个返回字符串的函数，该字符串将作为生成的辅助函数代码。
  • 参数：函数接收一个 options 对象，包含接口相关信息。

使用类型拓展 ​

  • 作用：在生成的接口类型定义中添加 [key: string]: any，以支持动态属性。
  • 适用场景：当接口返回数据包含动态字段时启用。

使用项目ID ​

  • 作用：在请求配置中添加项目ID，用于多项目环境下的请求区分。
  • 适用场景：当需要在请求中标识具体项目时启用。

基于 MIT 许可发布

Copyright © 2024