Apifox Helper 插件必须搜全称安装且重启IDEA才生效，社区版需≥2017.4、旗舰版≥2019.3；令牌和项目ID缺一不可，填错将静默失败，须通过Test Token验证连通性。
Apifox Helper 插件装不上？先确认名字和版本
搜不到 Apifox Helper，大概率是输错了插件名——它不是 Apifox、也不是 Apifox Uploader。JetBrains 插件市场里只有 Apifox Helper 这一个合法名称。
社区版 IDEA 要求 ≥ 2017.4，旗舰版 ≥ 2019.3；低于这些版本，插件即使安装成功也不会出现在 Settings → Other Settings 里。如果市场加载慢，直接去 JetBrains Marketplace 官网 下载 .zip 离线安装更稳。
装完必须重启 IDEA，否则：
• Settings 里找不到 Apifox Helper 配置入口
• 右键菜单不出现 Upload to Apifox
• 所有后续操作都无效
Hyperf 项目上传失败？检查注解兼容性
Hyperf 默认用 @Controller + @RequestMapping（或 @GetMapping/@PostMapping），这恰好是 Apifox Helper 原生识别的范围。但如果你用了自定义路由注解（比如 @MyRoute），插件默认跳过，不会解析任何接口。
补救方式只有加辅助注解：
- 在类上加
@Api（来自io.swagger.annotations.Api） - 在方法上加
@ApiOperation（同包） - 泛型返回值（如
ResponseData<User>）和路径变量默认值（如@PathVariable(value = "id", defaultValue = "1")）不会被自动提取，得靠@ApiParam或@ApiImplicitParam手动补全
注意：Hyperf 的 @Inject、@Value、@Middleware 等注解不影响文档生成，无需处理。
上传后 Apifox 端没更新？别只点刷新图标
点击 Apifox 右上角的 刷新 图标只是刷新当前视图缓存，不是拉取最新数据。真正同步依赖两个硬条件：
-
访问令牌必须有效且权限完整（需含api:write） -
项目 ID必须与 Apifox 云端项目完全一致（32 位十六进制字符串，区分大小写）
填错或漏填任一字段，上传操作会静默失败——IDEA 控制台不报错、Apifox 不提示、右键菜单也不灰掉。最稳妥的验证方式是点击 Settings → Other Settings → Apifox Helper → Test Token，看到 “✅ Connected” 才算通路正常。
另外，上传范围影响最终结果：
• 在 @Controller 类名上右键 → 上传该类下全部方法
• 在某个 @PostMapping 方法上右键 → 只传这一个接口
• 在 src/main/java 上右键 → 扫描整个源码目录，但若包路径非标准（如含 app/ 或多模块嵌套），可能漏类
Hyperf + ApiFox 文档字段缺失？重点查参数解析逻辑
Hyperf 的 @RequestBody 参数能被正确识别为请求体，但以下情况会导致字段丢失：
- DTO 类字段没加
@ApiModelProperty（Swagger 注解），且没开启 Lombok 的@Data+@Accessors(chain = true)，则插件无法反射出字段名和类型 - 使用
@Valid校验嵌套对象时，子对象未加@ApiModel，会导致嵌套结构显示为空对象 - Query 参数用
@RequestParam但没设required = false，插件默认标为必填，前端看文档会误判
Hyperf 的 @Json 序列化配置（如 @JsonInclude(JsonInclude.Include.NON_NULL)）不影响文档生成，但会影响 Mock 返回示例的字段可见性——这点容易被忽略，调试时发现示例缺字段，先回头检查 DTO 的序列化注解。
