Spring Boot 3中Springdocs/Swagger UI路径自定义异常问题

问题根源 #

出现Petstore演示页面的核心原因是Swagger UI没有正确关联到你的自定义API文档地址，默认 fallback 到了官方演示地址。具体问题点：

1. 仅配置了swagger-ui.config-url和path，但未明确指定swagger-ui.url指向你的api-docs路径，导致Swagger UI无法定位到你的API元数据。
2. 手动配置的config-url路径逻辑有误，springdoc中swagger配置的路径是基于api-docs.path自动生成的，无需手动拼接错误路径。

修复方案 #

方案1：修正springdoc配置，明确关联API文档 #

修改application.yaml，添加swagger-ui.url指向你的自定义API文档路径，同时修正config-url：

springdoc:
  api-docs:
    path: '/api/admin/v3/api-docs'
  swagger-ui:
    url: '/api/admin/v3/api-docs'  # 直接指向你的API文档JSON地址
    config-url: '/api/admin/v3/api-docs/swagger-config'
    path: '/api/admin/swagger-ui.html'

方案2：统一配置WebFlux基础路径（更简洁推荐） #

如果反向代理的前缀是/api/admin，直接配置WebFlux的base-path，所有请求路径会自动带上该前缀，springdoc的路径也会自动适配，无需单独配置每个路径：

server:
  webflux:
    base-path: '/api/admin'

springdoc:
  swagger-ui:
    path: '/swagger-ui.html'  # 最终访问路径自动变为 /api/admin/swagger-ui.html

配置后自动生成的路径：

• API文档：http://localhost:8080/api/admin/v3/api-docs
• Swagger UI：http://localhost:8080/api/admin/swagger-ui.html

验证步骤 #

1. 重启服务后，先访问http://localhost:8080/api/admin/v3/api-docs，确认能返回你的API JSON元数据。
2. 再访问Swagger UI地址，此时应该加载你自己的API文档，而非Petstore演示内容。

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