apifox-api

一个命令行工具，把当前工作目录绑定到 Apifox 项目，搜索接口并生成 TypeScript 类型。数据来自 Apifox 的 OpenAPI 导出 API，按 Module 缓存到本地。

安装

npm install -g apifox-api

或直接用 npx / bunx，无需全局安装。

快速开始

1. 获取 Apifox projectId 和 Access Token

• projectId：Apifox 项目设置 → 基本设置 → 项目 ID
• Access Token：Apifox 账号设置 → API 访问令牌，新建一个个人令牌

2. 绑定当前工作目录

在你的业务项目根目录运行：

apifox-api init <projectId> --authKey <your-access-token>

如果要绑定多个模块：

apifox-api init <projectId> --moduleIds 5,8,12 --authKey <your-access-token>

绑定信息写入全局注册表 ~/.apifox-api.json（以工作目录为 key，一台机器可同时绑定多个项目）。init 会立即拉取每个 module 的 OpenAPI 快照并缓存到当前目录的 .cache/apifox-api/ 下。

不想把 token 写进文件？省略 --authKey，改用 APIFOX_AUTH_KEY 环境变量（运行时 env 优先于文件中的值）。重新 init 同一目录会覆盖旧绑定并打印 before/after。

3. 搜索与生成类型

# 搜索接口（支持多关键词，默认 or 模式）
apifox-api search 订单 退款

# 按 HTTP 方法过滤
apifox-api search 订单 --method GET

# 为某个接口生成 TS 类型（method + path 来自搜索结果）
apifox-api get GET /orders/{id}

search 输出一个 markdown 表格（方法 / 路径 / 名称 / Tags），并报告命中总数与是否截断。get 输出请求参数、请求体和主成功响应的 TypeScript 类型。

命令

| 命令 | 说明 | |---|---| | init <projectId> [--moduleIds 5,8,12] [--authKey <token>] | 绑定当前目录到 Apifox 项目，写入 ~/.apifox-api.json，并首次拉取每个 module 的快照 | | search <keyword...> [--mode or\|and] [--method GET] [--limit 20] [--moduleId N] | 在当前 module 内搜索接口候选 | | get <method> <path> [--moduleId N] | 为指定接口生成 TypeScript 类型（Operation Key = method + path） | | refresh | 刷新当前项目全部 module 的 OpenAPI 快照 | | module [moduleId] | 查看当前 module 与全部 moduleIds，或切换当前 module | | config set-auth-key <token> | 设置全局默认 Apifox Auth Key（所有未单独配置 authKey 的项目回退到它） |

模块（Module）

一个 Apifox 项目可包含多个模块。init --moduleIds 绑定你关心的模块：

• 单 module：自动作为当前 module，无需切换，也不生成 .current-module。
• 多 module：init 生成 .current-module 文件标记当前模块（默认指向第一个）；用 apifox-api module <id> 切换。
• search 和 get 只在当前 module 的快照内工作，不跨 module 混搜。
• 临时只查一次别的 module：加 --moduleId N。
• 不传 --moduleIds：使用项目的默认模块。

缓存

每个 module 的 OpenAPI 快照单独缓存到绑定目录的 .cache/apifox-api/ 下，文件名包含 projectId、moduleId、auth 指纹与导出参数 hash。默认 TTL 24 小时，可用环境变量覆盖：

APIFOX_MCP_OPENAPI_TTL_MS=86400000

读取时若远程刷新失败，会回退到同 token 的过期缓存并附带警告；显式 refresh 永不回退，远程失败即报错。

从旧版（apifox-mcp MCP server）迁移

旧版是 MCP server + 工作区 .apifox-mcp.json。升级后：

• 在业务项目根目录运行 apifox-api init <projectId> --authKey <token>，会自动检测并迁移旧 .apifox-mcp.json 中的 projectId。
• 旧文件 .apifox-mcp.json 不再生效，建议手动删除。

开发

bun install
bun test
bunx tsc --noEmit
bun run build

AI 协作

本仓库附带一份 Cursor Agent Skill（.cursor/skills/apifox-api/SKILL.md），告诉 AI 何时先 search 再 get、Operation Key 的概念、以及多 module 项目如何切换当前 module。