api2apifox

解析本地 Spring Boot 源码 → 生成 OpenAPI 3.0 → 一键同步到 Apifox 项目。 Java 接口解析与 Apifox 同步工具，对标 IDEA 版 Apifox Helper，提供两种形态：

命名说明：项目名称、Marketplace 扩展 ID（duyiliu.api2apifox）与内部 CLI 包名（@duyiliu/api2apifox）已统一为 api2apifox；早期曾用名 Apifox Helper / ApiGen for Apifox 只保留在下列兼容标识里，均不可更改，改了会破坏既有团队规则、用户配置、快捷键与既有命令调用：

• 工作区规则文件名 .apifox-helper.properties（与 IDEA 版 Apifox Helper / easyyapi 共用）；
• 扩展设置前缀 apifoxHelper.*（含 apifoxHelper.helperProperties.* 等全部配置键）；
• 扩展命令 ID 前缀 apifoxHelper.*（package.json 中 contributes.commands 的 command 字段）、视图容器 ID apifoxHelper 与视图 ID apifoxHelper.apiTree（含 viewsWelcome、menus 的 when/command 引用）。

✨ 特性亮点

• 零配置:打开 Java 工程即可解析,不需要 JDK、不需要 LSP、不需要启动应用
• 源码不出本机:纯静态解析(基于 java-parser),源码不会上传到任何服务器,只有生成的文档数据会发送到 Apifox 开放 API
• 依赖 jar 类型还原:自动发现本地 Maven 仓库,按需解析 .class 字节码,把源码之外的类型(如自定义 ResponseDto<T>、MyBatis-Plus 的 Page)还原为完整模型——字段、泛型、@ApiModelProperty 描述均可带出,与 IDEA 插件的 classpath 能力等效
• 规则引擎兼容:识别 .apifox-helper.properties 声明式规则(与 IDEA 版 Apifox Helper / easyyapi 兼容的子集),团队既有规则可直接复用
• 细粒度同步:整个项目 / 单个文件 / 单个接口,随取随传
• Agent Skill 一等公民:自带 CLI 运行时,装 Skill 即用,无需 npm 全局安装;与扩展共用同一套解析与同步管线,--format json 输出稳定信封 + 语义化退出码,AI Agent / CI 开箱即用

📟 Agent Skill（AI Agent / CI / 脚本）

不依赖 VS Code，直接扫描 Java 项目、生成 OpenAPI 3.0 并同步到 Apifox。Skill 自带完整 CLI 运行时，安装 Skill 即完成安装，不再需要 npm install -g；与扩展共用同一套解析与同步管线，能力完全等价。要求 Node.js ≥ 20。

安装

npx skills add duyiliu/api2apifox --skill api2apifox -g

• -g 安装到用户级 Skill 目录（通常 ~/.agents/skills/api2apifox），其他 Agent 客户端按各自规则同步/链接。
• 固定版本：npx skills add duyiliu/api2apifox#v0.4.2 --skill api2apifox -g（扩展与 Skill 共用同一个 vX.Y.Z tag）。
• 国内网络：npx skills-cn@latest add duyiliu/api2apifox --skill api2apifox -g -y。
• 安装后自检：node "<skill-dir>/scripts/check-runtime.mjs"；校验失败说明 Skill 副本损坏，应重新安装，不要改用其它工具顶替。
• 升级：npx skills update api2apifox -g（装指定版本重新执行带 #vX.Y.Z 的 add 命令）；卸载：npx skills remove api2apifox -g。
• 离线/内网：从 GitHub Releases 下载 api2apifox-skill-<版本>.zip，解压为 ~/.agents/skills/api2apifox/（目录内含 SKILL.md、scripts/、runtime/），再执行自检命令。

常用命令

Skill 的 CLI 入口是 <skill-dir>/scripts/api2apifox.mjs；下文的 api2apifox 均指该入口。手工调用时展开为真实路径，例如：

# macOS / Linux
node "$HOME/.agents/skills/api2apifox/scripts/api2apifox.mjs" scan --project . --format json

# Windows PowerShell
node "$env:USERPROFILE\.agents\skills\api2apifox\scripts\api2apifox.mjs" scan --project . --format json

api2apifox scan --project . --format json                    # 扫描并输出接口清单
api2apifox export --project . --output openapi.gen.json      # 导出 OpenAPI 3.0 文件
api2apifox export --project . --stdout                       # OpenAPI 直接输出到 stdout
api2apifox sync --project . --project-id 123456 --dry-run --format json  # 同步预演(不写入)
API2APIFOX_TOKEN=APS_xxx api2apifox sync --project . --project-id 123456 --yes --format json
api2apifox config --project . --format json                  # 查看生效配置

VAR=xxx cmd 是 bash 写法；PowerShell 需先 $env:API2APIFOX_TOKEN = "APS_xxx" 再执行命令，cmd 用 set API2APIFOX_TOKEN=APS_xxx。

sync 真正写入后会在浏览器自动弹出同步结果报告页（汇总计数、错误警告、接口清单，同 VS Code 结果面板）；--no-report 可关闭。

范围与筛选

api2apifox scan --file path/to/UserController.java
api2apifox scan --endpoint "GET /api/users" --format json
api2apifox scan --include "**/src/main/java/**/*.java" --exclude "**/target/**"

• --file / --endpoint 可重复，为解析后过滤；要减少扫描量请用 --include / --exclude（注意二者是整体替换默认列表，不是追加）。
• --dependency-repo <dir> / --dependency-jar <path> 可补充 Maven 仓库与依赖 jar。

配置文件与 AI 调用约定

项目根目录可创建 .api2apifox.json（projectId、apiBaseUrl、include/exclude、冲突策略、pageTypeStyle 等）；配置优先级：CLI 参数 > API2APIFOX_* 环境变量 > .api2apifox.json > 默认值。

• Token 不允许写入配置文件，请用 API2APIFOX_TOKEN（及 API2APIFOX_PROJECT_ID）环境变量。
• --format json 时 stdout 只输出一个 JSON 信封，按 ok / error.code 分支；--quiet 隐藏非致命告警。
• 稳定退出码：0 成功 / 2 参数或确认错误 / 3 无 Java 文件或目标接口 / 4 鉴权错误 / 5 网络或服务错误 / 6 导入部分失败 / 7 本地错误；完整表见 SKILL.md。
• 真正同步必须在交互终端确认或显式传 --yes；首次导入可能较慢，超时上限默认 300s，可用 --timeout-ms 调整。返回 REQUEST_TIMEOUT 时请先查询目标项目再重试。

Skill/CLI 与 VS Code 扩展的配置相互独立：Skill/CLI 读取 .api2apifox.json、API2APIFOX_* 环境变量与命令行参数；扩展只读取 VS Code 设置 apifoxHelper.*，令牌保存在 VS Code SecretStorage。两边需分别配置，改一边不会影响另一边。

完整参数表见 skills/api2apifox/references/cli.md；packages/cli/README.md 保留为 CLI 内部构建源的参数参考。

📦 安装扩展（VS Code / Cursor）

• 扩展市场（VS Code）:在扩展面板搜索 api2apifox,或直接访问 Marketplace 页面安装(要求 VS Code ≥ 1.85)
• Cursor / 离线安装:扩展未上架 Open VSX(Cursor 默认市场),请从 GitHub Releases 下载最新 api2apifox-<版本>.vsix,执行命令 Extensions: Install from VSIX... 安装

🚀 快速上手（扩展）

1. 用 VS Code / Cursor 打开一个 Spring Boot 工程
2. 点击活动栏的 api2apifox 图标,打开顶部设置中心,填入并验证 Apifox 访问令牌,再选择目标项目(也可执行命令 api2apifox: 选择 Apifox 项目)
3. 刷新接口列表,浏览解析出的全部接口(按模块/控制器分组)
4. 选择一种方式同步:整个项目 / 勾选的接口 / 当前文件 / 光标处单个接口;批量同步前会确认目标项目、接口数量与冲突策略
5. 可选:执行 导出 OpenAPI 预览文件,生成 openapi.gen.json 本地验证

🧩 功能总览

🖥 接口列表视图（扩展）

• 浏览:侧边栏「接口列表」按接口目录分组展示工作区解析出的所有接口,目录 key 含 / 时逐级嵌套(如 测评工作站/测评量表-CARS);目录默认收起,手动展开/收起后刷新保持;保存 Java 文件后自动刷新(侧边栏不可见时延迟到下次可见)
• 快速过滤:点击标题栏漏斗图标输入关键词(支持 URL 路径、中文描述、HTTP 方法、Controller 类名等),支持多词组合(空格分隔),实时保留匹配项并高亮关键字;过滤激活时常驻一行 🔍 "关键字" · 命中数/总数,一键清除
• 搜索并跳转:放大镜图标弹出 QuickPick,模糊匹配接口,回车直接跳转到源码定义
• 批量勾选:过滤状态下「全选」仅勾选当前命中接口;若存在过滤隐藏的已选项,同步时会明确选择“仅当前过滤”或“全部已选”;勾选按 Apifox 项目隔离并跨会话保持

同步命令（VS Code 命令）

⚙️ 扩展设置

设置中心保存的项目绑定(projectId/projectName/teamName/apiBaseUrl 等)写入工作区 .vscode/settings.json,会随仓库提交共享给团队(便于成员共用同一目标项目);访问令牌始终存在系统 SecretStorage,不落任何文件。

📄 .apifox-helper.properties 支持

支持 IDEA 版 Apifox Helper(easyyapi 规则引擎)的声明式规则子集,文件放工作区/模块根目录即可,无需额外配置:

条件后缀:key[#tag]=...、key[@全限定注解]=...、key[!@注解]=...(取反)。

与 IDEA 版的差异/边界:

• 不嵌入 Groovy/JS 运行时。groovy:/js: 值仅支持「纯字符串拼接 + it.ann("注解","属性")」的安全形态(典型如 field.doc[@ext.plus.common.core.annotation.DataDic]=groovy: "（框架字典：" + it.ann("ext.plus.common.core.annotation.DataDic", "value") + "）" 可直接使用);其余脚本不执行,并以告警提示跳过(不会静默)
• 三元条件的条件侧额外支持字段访问器:it.name()(字段名)、it.type()?.name()(声明类型原文)、it.type()?.simpleName()(根简单名),可接 ==/!=/null 比较或 equals/equalsIgnoreCase/startsWith/endsWith/contains/matches 字符串方法。典型用法——把雪花 ID 字段按 string 文档化(对齐「大整型序列化为字符串」的框架契约):field.type=groovy: ((it.name() == "id" || it.name().endsWith("Id")) && (it.type()?.name()?.endsWith("Long") || it.type()?.name() == "long" || it.type()?.name()?.endsWith("BigInteger"))) ? "string" : null
• 类/方法/字段规则的 #tag、注解、字面量写法与官方一致
• 不读取 application.{yml|properties} 做 spring 配置属性解析,不支持 module/export.*/api.class.parse.* 等回调类规则
• 无法安全执行的规则会出现在同步/导出的告警里,格式:<key> 的 groovy/js 规则无法在无脚本运行时下安全执行,已跳过:...

❓ FAQ

需要安装 JDK 或启动应用吗? 不需要。纯静态解析源码与依赖 jar 字节码,全程不启动进程。

源码会被上传吗? 不会。源码只在本地解析,发送到 Apifox 开放 API 的仅有生成的 OpenAPI 文档数据。

Apifox 是私有化部署能用吗? 能。将 apifoxHelper.apiBaseUrl 改为私有化部署的开放 API 地址即可。

支持 Kotlin / Gradle 吗? Kotlin 源码暂不支持(仅 Java)。Gradle 项目的依赖 jar 可通过 apifoxHelper.dependencyJars 显式指定。

⚠️ 已知边界

• Kotlin 不支持:需要第二套解析器(Kotlin 语法树),当前版本仅支持 Java 源码
• 依赖 jar 类型识别的边界:解析工作区 pom.xml 声明的直接依赖,并读取各 jar 内嵌 pom 再推断 2 轮传递依赖(jar 总数上限默认 120,可用 maxDependencyJars 调整;超出部分按依赖距离丢弃,告警会列出被丢弃的 jar 名);仍未覆盖的类型可通过 dependencyJars 显式补充;Gradle 项目请用 dependencyJars 显式指定;仓库中的同名类以先注册的 jar 为准
• 同项目内不同包下的顶层重名类型以简单名索引,后扫描到的覆盖先扫描到的(源码类型优先于 jar 类型;插件不做 import 解析,无法区分同名顶层类型)
• 类体/接口体内的嵌套类型按 Java 作用域解析:支持完整的多层成员路径及泛型包装中的嵌套实参,字段类型里的简单名优先命中本类成员,再由内向外回退到顶层类型。不同类型同名时追加 _2、_3 … 并告警;已完成的非递归同结构模型可复用,递归模型保留独立名称以保证引用准确
• 隐藏目录与工作区内另一处 git 检出不参与扫描:工作区根下任一 .xxx 目录的内容均跳过,因此 .kilo/worktrees、.claude/worktrees 和其他 AI 工具的隐藏工作目录不会产生重复接口；嵌套 git 检出同样按 .git 标记跳过。要扫描某个工作树,请将该工作树根目录作为独立工作区或多根工作区文件夹打开
• 查询 Bean 的集合字段以数组形态描述(如 deptCodes: array);IDEA 版会写成 deptCodes[0],只体现首个元素,故此处有意不一致
• 继承接口的泛型形参不做实例化绑定:abstract class Base<T> 的方法签名里引用 T 时按未绑定类型处理(如 T 直接落在 $ref/类型名上);抽象基类声明为具体类型的场景不受影响
• @ApiResponse 的 headers/links、@Digits、@Past/@Future 等未映射

🛠 开发与发布

仓库根目录的 work/ 存放内部设计文档与任务笔记（如 .apifox-helper.properties 支持的设计稿）；skills/ 是 Agent Skill 分发目录。二者都不参与 VSIX 发布。

# 要求 Node.js >= 20
npm install
npm run compile     # esbuild 打包到 dist/
npm test            # 解析器单测 + sample 项目端到端断言
npm run test:host   # VS Code 1.85 Extension Host smoke(激活/命令/single-flight/成功与失败恢复)
npm run test:vsix   # 已打包 vsix 的隔离 profile 安装+激活验证(默认用本机 VS Code,无则下载 1.85)
npm run package     # 打包 vsix(产物名 api2apifox-<版本>.vsix)
npm run build:skill # 重建 Skill 自带 CLI 运行时(skills/api2apifox/runtime)
npm run check:skill # 校验 Skill 运行时哈希与版本(发版/CI 使用)
npm run release -- X.Y.Z  # 统一版本:更新两个 package.json、重建 runtime、校验

在 VS Code 中调试:打开本目录后 F5(Extension Development Host),用 sample/ 目录作为测试工作区。

Skill 运行时由 packages/cli 的同一份 bundle 生成；改动 CLI 源码或运行 npm run release 后，必须提交 skills/api2apifox/runtime/，否则 CI 与发版工作流会因运行时过期而失败。 packages/cli 是内部构建源（private: true），不再单独发布 npm；VS Code 扩展的 Marketplace 发布保持不变。

统一发版（v*）

扩展与 Skill 使用同一个版本号：根 package.json 与 packages/cli/package.json 必须一致，tag 为 vX.Y.Z。推送 tag 后 .github/workflows/release.yml 自动完成：类型检查 → 扩展/CLI 测试 → 校验 Skill runtime → 打包 vsix 与 Skill zip → 发布 VS Code Marketplace（配置了 OVSX_PAT 时同时发布 Open VSX）→ 创建 GitHub Release（附带 vsix + Skill zip）。

首次需在仓库 Settings → Secrets and variables → Actions 添加：

• VSCE_PAT（Azure DevOps PAT，scope 勾选 Marketplace → Manage）——发布 VS Code Marketplace 必需。
• OVSX_PAT（可选）——发布 Open VSX，供 Cursor / Windsurf / VSCodium 用户从各自市场安装。获取方式：用 GitHub 账号登录 open-vsx.org → 在 Settings → Access Tokens 生成；首次还需在 open-vsx.org 创建与 publisher 同名的 namespace（duyiliu）。未配置时该步骤自动跳过。

日常发版：

npm run release -- X.Y.Z   # 或 npm run release:patch / release:minor / release:major
git add package.json packages/cli/package.json package-lock.json skills/api2apifox README.md
git commit -m "chore(release): vX.Y.Z"
git tag vX.Y.Z
git push origin main --tags  # 触发 release.yml

npm run release -- X.Y.Z 会：

• 校验根包与 CLI 版本一致
• 更新两个 package.json 与 package-lock.json
• 重建 skills/api2apifox/runtime
• 同步 README/SKILL.md/references 的版本示例
• 执行 check:skill

release:patch / release:minor / release:major 等价于传对应的版本增量。脚本只准备文件和校验，不自动 commit/tag/push。

📄 License

MIT