SpringDoc OpenAPI WebFlux中Swagger UI默认显示Petstore的问题分析与解决方案

问题背景

在使用Spring Boot 3.4.4版本配合springdoc-openapi-webflux-ui 2.8.6时，开发者发现访问Swagger UI默认页面时，系统会显示Petstore的示例API文档而非项目自身的API文档。虽然通过配置springdoc.swagger-ui.disable-swagger-default-url=true理论上可以禁用默认Petstore文档，但在WebFlux环境下该配置并未生效。

技术原理分析

这个问题源于Spring Boot和SpringDoc的资源处理机制冲突：

1. Spring Boot的默认行为：Spring Boot 3.4.4在WebFluxAutoConfiguration中为/webjars/**路径注册了CachingResourceTransformer，这会优先处理所有/webjars路径下的静态资源请求。

2. SpringDoc的配置：SpringDoc原本通过SwaggerWebFluxConfigurer为/swagger-ui路径注册了SwaggerIndexPageTransformer，但由于路径匹配问题，当用户访问/webjars/swagger-ui/index.html时，Spring Boot的默认处理器会优先介入。

3. 配置失效原因：disable-swagger-default-url配置需要通过SwaggerIndexPageTransformer生效，但由于上述路径处理优先级问题，该转换器未被正确触发。

解决方案

经过社区贡献者的分析，解决方案需要调整SpringDoc的资源处理器注册逻辑：

1. 路径匹配修正：将SwaggerIndexPageTransformer同时注册到/webjars/swagger-ui路径，覆盖Spring Boot的默认处理。

2. 配置生效：确保当用户设置disable-swagger-default-url=true时，转换器能够正确修改index.html内容，移除Petstore的默认配置。

实现细节

核心修改涉及SwaggerWebFluxConfigurer类的资源处理器注册逻辑：

// 修改前：只为/swagger-ui路径注册转换器
registry.addResourceHandler(uiRootPath + swaggerUiPrefix + ALL_PATTERN)
    .addResourceLocations(CLASSPATH_RESOURCE_LOCATION + resourcePath)
    .addTransformer(swaggerIndexTransformer);

// 修改后：同时为/webjars/swagger-ui路径注册
registry.addResourceHandler(uiRootPath + webjarsPrefix + SWAGGER_UI_PREFIX + ALL_PATTERN)
    .addResourceLocations(CLASSPATH_RESOURCE_LOCATION + resourcePath)
    .addTransformer(swaggerIndexTransformer);

最佳实践建议

1. 版本选择：建议使用包含该修复的SpringDoc版本（2.8.6之后）。

2. 配置方式：在application.yml中明确配置：

springdoc:
  swagger-ui:
    disable-swagger-default-url: true
    url: /v3/api-docs

3. 测试验证：部署后应直接访问/webjars/swagger-ui/index.html验证是否显示项目自身API文档。

技术延伸

这个问题揭示了Spring生态中一个重要概念：资源处理链的优先级。在WebFlux环境下，多个自动配置模块可能注册相同路径模式的资源处理器，开发者需要理解：

• 资源处理器的注册顺序影响最终行为
• 路径匹配的精确度决定处理器的触发条件
• 自定义配置需要确保覆盖默认行为

通过这个案例，开发者可以更好地理解Spring Boot自动配置与第三方库集成的潜在问题排查思路。