Spring Boot 3.x + Knife4j 接口分组配置踩坑记录

前言

最近在使用 Spring Boot 3.2.0 + Knife4j 4.4.0 来生成接口文档，项目分为管理端和用户端两个模块，
想要在 Swagger 文档中实现接口分组显示，之前总是偷懒，想着"拿来主义"，这次自己做配置的时候，
卡了半天，发现无论选择哪个分组，都会显示所有接口。

经过一番排查，终于找到了问题所在。在这里记录一下，希望能帮到遇到同样问题的朋友。

问题现象

配置了接口分组后，在 Knife4j 文档页面可以看到两个分组：

管理端接口分组：

用户端接口分组：

环境信息

• Spring Boot：3.2.0
• JDK：17
• Knife4j：4.4.0
• 依赖：knife4j-openapi3-jakarta-spring-boot-starter

我的配置

Java 代码配置

    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("管理端接口")
                .pathsToMatch("/admin/**") /*这里如果配置了 packagesToScan，注意不要和 pathsToMatch 冲突了*/
                .build();
    }

    @Bean
    public GroupedOpenApi userApi() {
        return GroupedOpenApi.builder()
                .group("用户端接口")
                .pathsToMatch("/user/**")
                .build();
    }

YAML 配置文件

# Knife4j配置
springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
  packages-to-scan: com.lumo.seatbooking.controller  # 问题就在这两行
  paths-to-match: /**  

一开始只做了管理端接口，后面才去添加用户端接口，在 Java 代码中添加了分组，却忽略了 YAML 配置文件中的全局配置。

检查的时候也以为是依赖问题，中间换成了 SpringDoc 官方的 Swagger UI ，还是不行。

问题原因

YAML 中的全局配置覆盖了 Java 代码中的分组配置！

当 YAML 中配置了 packages-to-scan 和 paths-to-match 时：

• 所有分组都会扫描 controller 包下的所有接口
• 所有分组都会匹配 /** 路径
• 导致 Java 代码中的 pathsToMatch("/admin/**") 和 pathsToMatch("/user/**") 配置失效

配置优先级：

YAML 全局配置 > Java 代码分组配置

解决方案

修改 application.yml

# Knife4j配置
springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs
  swagger-ui:
    enabled: true
    path: /swagger-ui.html
  # 不要配置这两行
  # packages-to-scan: com.lumo.seatbooking.controller
  # paths-to-match: /**

结果展示

总结

遇到类似的问题要记得检查：

1. 依赖冲突：检查 pom.xml 中是否有多个 Swagger 相关依赖
2. 配置覆盖：检查 YAML 配置文件是否有全局配置覆盖了局部配置
3. 路径匹配：确认 packagesToScan 和 pathsToMatch 的配置是否与实际的接口路径一致

---

如果觉得有帮助，欢迎点赞、收藏、关注！