基于路径路由的SpringDoc OpenAPI 3 Swagger-UI加载问题求助

1. 先确认Swagger的Base Path配置 #

你的应用挂载在/mailservice子路径下，Swagger默认的基础路径会和实际路由不匹配，导致CSS、JS这类静态资源请求404，直接引发页面加载异常。

不同框架的配置示例： #

• Spring Boot（SpringDoc）：在配置类里指定服务路径

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .servers(List.of(new Server().url("/mailservice")));
}

或者在application.yml里配置：

springdoc:
  swagger-ui:
    config-url: /mailservice/v3/api-docs/swagger-config
    urls[0].url: /mailservice/v3/api-docs

• Spring Boot（Swagger2）：

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .pathMapping("/mailservice");
}

2. 检查网关/反向代理的路由规则 #

如果用了Nginx、API网关做路径转发，必须确保静态资源请求能正确传递到后端。比如Nginx配置要注意proxy_pass的写法：

location /mailservice/ {
    proxy_pass http://你的邮件服务地址:端口/;
    proxy_set_header X-Forwarded-Prefix /mailservice;
}

别漏了proxy_pass末尾的斜杠，否则子路径会被截断，导致后端收不到完整的请求路径。

3. 看浏览器控制台找具体错误 #

按F12打开开发者工具，切到Network标签，看哪些请求失败了：

• 要是有404，就是静态资源路径不对，调整Swagger的资源映射配置就行
• 要是有CORS报错，就得在网关或者后端加跨域允许规则

4. 验证后端服务本身的Swagger是否正常 #

绕过网关，直接访问后端服务的Swagger页面（比如http://localhost:8080/swagger-ui/index.html）。如果能正常加载，问题肯定在网关的路由配置上；要是还是异常，那就是后端Swagger的配置本身有问题。

5. 确认context-path配置是否正确 #

如果后端服务设置了server.servlet.context-path=/mailservice，那所有端点都会带上这个前缀，包括Swagger的资源。这种情况下，网关只需要把/mailservice路径转发到后端根路径就行，不用额外处理路径拼接。

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