pull-apifox

从 Apifox 拉取接口，按需筛选，自动生成带完整 JSDoc 的 JS 请求函数。

安装

npm install -g pull-apifox

快速开始

1. 创建配置文件 apifox.config.json

{
  "projectId": "1577893",
  "accessToken": "aps-xxxxxxxxxx",
  "output": "./src/apifox",
  "showReturns": true,
  "importPath": "@/utils/request",

  "pull": [
    {
      "tags": ["移库单管理"],
      "name": "womeiTransfer",
      "prefix": "/chainova/wms"
    }
  ]
}

2. 运行

pull-apifox
# 或指定配置文件
pull-apifox ./path/to/apifox.config.json

配置文件

顶层配置

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | projectId | string | 必填 | Apifox 项目 ID，从项目 URL 中获取 | | accessToken | string | — | Apifox 访问令牌，填了走云端 API，不填走本地客户端 | | localPort | number | 4523 | 本地客户端端口 | | output | string | ./src/apifox | 默认输出目录 | | showReturns | boolean | false | 是否在 JSDoc 中展开返回值类型 | | importPath | string | @/utils/request | 生成的 import 语句中的 request 路径 | | pull | array | 必填 | 拉取任务列表，每项生成一个 JS 文件 |

pull 筛选规则

每项支持三个筛选维度，folder 为 AND 划定范围，tags 与 apis 为 OR 取并集：

| 字段 | 类型 | 说明 | 示例 | |------|------|------|------| | folder | string | Apifox 接口文档 ID（数字）或 URL 路径前缀 | "83863684" 或 "/movement-orders" | | tags | string[] | Apifox 标签，支持层级模糊匹配 | ["移库单管理"] 可匹配 "沃美/移库单管理" | | apis | string[] | 接口名关键词；以 / 开头时精确匹配路径 | ["login"] 或 ["/storage/location/list"] |

pull 输出配置

| 字段 | 类型 | 说明 | |------|------|------| | name | string | 生成的文件名，如 "user" → user.js。指定后所有命中接口合并到此文件 | | prefix | string | 请求路径前缀，会加到每个 URL 前面 | | output | string | 可选的独立输出目录，覆盖顶层 output |

筛选逻辑详解

folder AND (tags OR apis)

• folder 为 AND：先划定范围（接口文档 ID 通过 Apifox API scope 限定，路径字符串通过 URL 前缀匹配）
• tags 与 apis 为 OR：只要满足任一条件即命中
• 未指定的维度视为「全部匹配」

apis 匹配规则：

| 关键词格式 | 匹配方式 | 示例 | |-----------|---------|------| | 以 / 开头 | 精确路径 | "/storage/location/list" 只匹配该路径 | | 其他 | 模糊匹配 | "login" 匹配 operationId、summary、路径末段 |

tags 匹配规则：

Apifox 导出的标签通常包含层级路径，如 沃美/移库单管理。配置 "移库单管理" 即可匹配，支持：

• 完全相等："移库单管理" = "移库单管理"
• 末级匹配："移库单管理" 匹配 "沃美/移库单管理"
• 中间层级："沃美" 匹配 "沃美/移库单管理"

folder 规则：

• 纯数字（如 "83863684"）→ 作为 Apifox 接口文档 ID，通过 API scope 限定拉取范围；API 不支持时退化到全量拉取
• 路径字符串（如 "/movement-orders"）→ URL 前缀匹配，子路径自动包含

配置示例

按接口文档 ID 拉取

{
  "projectId": "1577893",
  "accessToken": "afxp_xxxxxx",
  "output": "./src/apifox",

  "pull": [
    {
      "folder": "83863684",
      "tags": ["移库单管理"],
      "apis": ["/storage/location/list"],
      "name": "womeiTransfer",
      "prefix": "/chainova/wms"
    }
  ]
}

folder: "83863684" 限定接口文档范围，tags + apis 在范围内取并集。

按路径前缀拉取

{
  "pull": [
    {
      "folder": "/movement-orders",
      "name": "movement",
      "prefix": "/chainova/wms"
    }
  ]
}

匹配所有 /movement-orders/xxx 下的接口。

多组拉取

{
  "pull": [
    {
      "tags": ["移库单管理"],
      "name": "womeiTransfer",
      "prefix": "/chainova/wms"
    },
    {
      "apis": ["/lite/logical/inventory/transaction/page"],
      "name": "transaction",
      "prefix": "/chainova/wms"
    },
    {
      "tags": ["项目管理"],
      "name": "projectManager",
      "prefix": "/chainova/srm"
    }
  ]
}

同 folder 的组会复用缓存，避免重复拉取。

获取 Access Token

1. 打开 Apifox
2. 右上角头像 → 账号设置 → 访问令牌
3. 点击 新建令牌，复制填入 accessToken

生成结果

src/apifox/
├── index.js                  # 入口，聚合导出
└── api/
    └── womeiTransfer.js       # 接口函数，带完整 JSDoc

生成代码示例

import request from '@/utils/request';

/**
 * 新建移库单
 *
 * POST /movement-orders/create
 * @param {object} data - 请求体
 * @param {string} data.ownerCorpCode - 货主企业编码
 * @param {string} data.warehouseCode - 仓库编码
 * @param {string} [data.remark] - 备注
 * @param {object[]} data.items - 移库单项列表
 * @param {string} data.items[].skuCode - SKU编码
 * @param {number} data.items[].quantity - 数量
 * @returns {Promise<object>} - 响应数据
 * @param {number} returns.code - 状态码
 * @param {string} returns.message - 返回消息
 */
export function createMovementOrder(data) {
  return request({
    url: '/chainova/wms/movement-orders/create',
    method: 'POST',
    data,
  });
}

函数参数命名规则

| 参数位置 | 形参名 | 说明 | |----------|--------|------| | 路径参数 {id} | id | 直接展开为独立参数 | | 查询参数 ?page=1 | params | 所有 query 合并为一个 object | | 请求体 | data | body 对象 |

在业务代码中使用

// 从入口聚合导入
import { createMovementOrder, getMovementOrderList } from '@/apifox';

// 或按文件导入
import { createMovementOrder } from '@/apifox/api/womeiTransfer';

更新接口

Apifox 上接口变更后，重新运行即可覆盖生成文件：

pull-apifox

生成文件头部已标注 由 pull-apifox 自动生成，请勿手动修改。建议通过修改配置文件来调整输出，而不是直接改生成文件。

License

MIT