SpringFox Swagger3.0.0自定义swagger-ui访问路径报错排查

安全阿岳

2026-9-3

问题根因

Springfox 3.0.0版本自带的springfox.documentation.swaggerUi.baseUrl配置项存在实现缺陷，无法自动完成Swagger UI静态资源的路径映射；同时你的项目是Spring Cloud Gateway的WebFlux运行环境，之前使用的@EnableSwagger2是Servlet环境专属注解，WebFlux环境下不会生效，双重问题导致Swagger前端加载时无法定位api-docs端点地址，触发"Unable to infer base url"报错。
你之前尝试的仅修改yml配置、迁移@EnableSwagger2注解位置的方案，没有解决核心的资源映射和注解适配问题，因此无法生效。

落地解决方案

按以下步骤操作即可满足需求，全程不会改动原有业务API的路径规则：

第一步：删除application.yml中之前新增的所有springfox开头的自定义路径配置，避免和后续转发规则冲突。
第二步：替换Swagger启用注解，将项目中（不管是在独立配置类还是主启动类上）的@EnableSwagger2注解删除，替换为WebFlux环境专用的@EnableSwagger2WebFlux注解，保证Swagger文档端点正常注册。
第三步：新增如下路由配置类，仅对customDir路径下的Swagger相关请求做转发，完全不会拦截原有/sys1、/sys2开头的业务API请求：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.reactive.function.server.RouterFunction;
import org.springframework.web.reactive.function.server.ServerResponse;
import java.net.URI;
import static org.springframework.web.reactive.function.server.RequestPredicates.GET;
import static org.springframework.web.reactive.function.server.RouterFunctions.route;

@Configuration
public class CustomSwaggerPathConfig {
    @Bean
    public RouterFunction<ServerResponse> customSwaggerRoute() {
        // 访问/customDir时自动跳转到swagger-ui页面
        return route(GET("/customDir"),
                        req -> ServerResponse.seeOther(URI.create("/customDir/swagger-ui.html")).build())
                // 转发customDir路径下的所有swagger静态资源请求
                .andRoute(GET("/customDir/**"), req -> {
                    String targetPath = req.path().replaceFirst("/customDir", "");
                    return ServerResponse.ok().render("forward:" + targetPath);
                })
                // 转发api-docs文档端点请求
                .andRoute(GET("/customDir/v2/api-docs"),
                        req -> ServerResponse.ok().render("forward:/v2/api-docs"))
                .andRoute(GET("/customDir/v3/api-docs"),
                        req -> ServerResponse.ok().render("forward:/v3/api-docs"))
                // 屏蔽根路径默认的swagger入口，避免未授权访问
                .andRoute(GET("/swagger-ui.html"),
                        req -> ServerResponse.seeOther(URI.create("/")).build());
    }
}

效果验证

业务接口不受影响：所有原有/sys1/**、/sys2/**路径的REST API完全不会被上述配置拦截，访问规则和之前完全一致。
Swagger访问符合要求：访问mydomain.com/customDir/swagger-ui.html时可以正常加载文档页面，不会再弹出base url推断错误，浏览器地址栏会保持customDir路径前缀。
权限管控适配：后续直接给/customDir/**路径配置专属访问权限规则即可，未授权用户无法访问该路径下的Swagger资源，根路径默认的Swagger入口已经被屏蔽，不会出现未授权暴露文档的问题。

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