Springdoc 1.8 Swagger UI在多模块Maven项目中部分服务无法访问

问题背景 #

我们有一个基于Spring Boot 2.7的Maven多模块项目，包含两个MVC REST API模块和一个公共模块。两个REST API模块分别构建为独立服务，通过java -cp命令部署在不同服务器：

• 其中一个模块添加以下依赖后，可正常访问Swagger UI（http://localhost:8091/swagger-ui/index.html）：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.8.0</version>
</dependency>

• 另一个模块添加相同依赖后，访问对应URL返回404且日志无报错。两个服务结构相似，均包含@RestController、@RestMapping及实现WebMvcConfigurer的WebConfiguration类，且配置一致。
• 若将该依赖添加到公共模块、移除两个REST模块的依赖，仅能显示原正常模块的REST API。

调试步骤 #

1. 排查依赖传递与版本冲突 #

• 分别在两个REST模块根目录执行mvn dependency:tree，输出依赖树，确认springdoc-openapi-ui及其核心依赖（如springdoc-openapi-webmvc-core）是否被正确引入。
• 对比两个模块的依赖树，重点检查是否存在其他依赖引入了不同版本的springdoc组件，或是否有<exclusions>规则排除了相关依赖。

2. 验证Spring Boot自动配置状态 #

• 在有问题的模块启动时添加--debug参数，查看控制台输出的自动配置报告，确认SpringDocAutoConfiguration、SwaggerUiAutoConfiguration等springdoc相关配置类是否被加载。
• 检查自定义WebConfiguration类：如果加了@EnableWebMvc注解，会禁用Spring Boot的自动配置逻辑，可能导致springdoc配置失效，对比两个模块的该类注解是否一致。

3. 检查静态资源映射配置 #

• 查看有问题模块的WebMvcConfigurer实现类中addResourceHandlers方法，确认是否覆盖了默认静态资源映射规则，导致Swagger UI的静态文件（如swagger-ui/index.html）无法被访问。
• 临时注释自定义的静态资源配置，重启服务测试Swagger UI是否可访问，逐步定位问题点。

4. 确认API扫描范围 #

• 在有问题模块的配置文件中显式指定springdoc的扫描路径，验证是否能扫描到控制器：

  springdoc.packages-to-scan=你的控制器所在包路径
  springdoc.paths-to-match=/**
  

• 对比两个模块的包结构，确认控制器所在包是否在Spring Boot默认扫描范围内（启动类所在包及其子包）。

5. 验证部署类路径完整性 #

• 检查有问题模块的java -cp启动命令，确认所有依赖jar包（尤其是springdoc相关jar）都被正确加入classpath。可以打印当前类路径进行核对：

  java -cp 你的类路径 -verbose:class org.springframework.boot.loader.JarLauncher
  

• 对比两个模块的启动命令，排查是否存在类路径遗漏或差异。

6. 检查公共模块依赖传递规则 #

• 当依赖移到公共模块时，确认公共模块的pom.xml中该依赖的<scope>为compile（默认值，可传递）。
• 在有问题的REST模块执行mvn dependency:tree，确认是否从公共模块正确继承到springdoc依赖，若未获取到，检查是否存在依赖排除规则。

7. 单独测试OpenAPI文档生成 #

• 在有问题的模块中添加测试控制器，验证OpenAPI文档是否正常生成：

  @RestController
  public class SwaggerDebugController {
      @Autowired
      private OpenAPI openAPI;
  
      @GetMapping("/v3/api-docs")
      public OpenAPI getOpenApiDoc() {
          return openAPI;
      }
  }
  

  访问/v3/api-docs，若能返回JSON文档，说明问题出在Swagger UI静态资源映射；若返回404，说明OpenAPI生成逻辑未生效。

内容的提问来源于stack exchange，提问作者John Little