若依集成Magic-API后接口无法自动注册到Swagger？

Question

若依（RuoYi）集成 Magic-API 后，其动态生成的 REST 接口无法自动出现在 Swagger（如 Swagger2 或 SpringDoc）文档中，是典型兼容性问题。根本原因在于：Magic-API 通过 `HandlerMapping` 动态注册接口，绕过了 Spring MVC 的标准 `@RequestMapping` 注解扫描机制；而 Swagger 默认仅解析显式声明的 `@RestController` + `@ApiOperation` 等注解类，无法感知 Magic-API 运行时注入的 `RequestMappingInfo`。此外，若依默认启用的 Swagger2（基于 `springfox-swagger2`）不支持非 Bean 形式的 Handler，且 Magic-API 的 `MagicController` 未被 Swagger 的 `Docket#apis()` 扫描路径覆盖，导致接口“存在但不可见”。该问题在若依 Vue/Vue3/Cloud 多版本中均复现，需通过自定义 `DocumentationPlugin` 或适配 SpringDoc 的 `OperationCustomizer` 方式实现元数据注入，而非简单配置包扫描路径。

Answer 1

```html

一、现象层：接口“存在但不可见”的典型表现

• 若依（RuoYi）系统成功集成 Magic-API，管理界面可创建、调试并执行动态 SQL 接口（如 /api/magic/user-list）；
• 浏览器直接访问该 URL 返回正常 JSON 数据，证明接口运行时注册成功；
• 但 Swagger UI（/swagger-ui.html 或 /swagger-ui/index.html）中完全不显示该接口；
• 若依 Vue 前端调用 SwaggerClient 获取 API 列表时，返回空数组或缺失字段；
• 日志中无报错，HandlerMapping 日志可见 Magic-API 的 RequestMappingInfo 已注册，但 DocumentationPluginsManager 未捕获。

二、机制层：Spring MVC 与 Swagger 的双重解耦原理

下图展示了 Magic-API 动态接口在 Spring 生态中的“隐身”路径：

flowchart LR
    A[Magic-API 编辑器] --> B[解析 Groovy/SQL 生成 HandlerFunction]
    B --> C[通过 MagicHandlerMapping.registerMapping\(\) 注册]
    C --> D[注入 RequestMappingInfo 到 RequestMappingHandlerMapping]
    D --> E[Spring MVC DispatcherServlet 可路由]
    E -.->|未暴露元数据| F[Swagger2: Docket#apis\(\) 扫描 @RestController 类]
    E -.->|无 @ApiOperation 注解| G[SpringDoc: OperationCustomizer 无匹配 Bean]
    F & G --> H[接口文档“黑洞”]

三、根因层：三大技术断点深度剖析

断点维度	Swagger2（springfox）	SpringDoc（OpenAPI 3）
扫描机制	仅扫描 @Api/@ApiOperation 注解的 Controller Bean	依赖 @Operation + @RestController Bean 元数据反射
Handler 形式	要求 Handler 必须为 Spring Bean（@Controller），MagicController 是 prototype 且非标准 Bean	支持 HandlerMethod，但需显式注册到 OpenApiResource 上下文
元数据来源	静态注解驱动，无法读取运行时 RequestMappingInfo 的 pathPatterns、methods、consumes	默认忽略非 @RestController Bean 的 HandlerMapping 注册项

四、解法层：面向生产环境的双轨适配方案

1. Swagger2 兼容路径：继承 DocumentationPlugin，重写 createResourceGroup，从 RequestMappingHandlerMapping 中提取 Magic-API 的 HandlerMethod 并构造 ResolvedMethodParameter 和 ApiDescription；
2. SpringDoc 主流路径：实现 OperationCustomizer + OpenApiCustomiser，在 customise 阶段手动注入 Paths 对象，基于 MagicApiService.getAllApiInfos() 构建 PathItem 与 Operation；
3. 若依适配要点：需在 RuoYiConfig.java 或 SwaggerConfig.java 中排除 magic-api 包的自动扫描，改由 @PostConstruct 触发元数据同步；
4. 安全增强：对接若依的 ShiroFilterFactoryBean 或 SecurityFilterChain，确保文档中展示的 Magic-API 接口已通过权限校验逻辑（如 @RequiresPermissions("magic:api:view")）；

五、验证层：全链路回归检查清单

• ✅ 启动后日志输出 [MagicSwaggerSync] Registered 17 dynamic APIs to OpenAPI；
• ✅ Swagger UI 中出现 magic-api 分组，含完整 GET/POST 标签、参数表格、Model Schema；
• ✅ 点击 Try it out 可正确带入若依 Token（X-Access-Token）并返回模拟响应；
• ✅ 若依 Cloud 版本中，网关层（Spring Cloud Gateway）路由与文档路径前缀一致（如 /api/magic/**）；
• ✅ CI 流程中增加 curl -s http://localhost:8080/v3/api-docs | jq '.paths | keys' 断言检测。

```