Springfox Swagger UI反向代理配置问题：Base URL显示异常

我之前在反向代理部署Spring Boot + Swagger的时候也碰到过一模一样的Base URL显示问题——明明外部访问路径是localhost:8082/api，Swagger UI却硬显示localhost:8080，折腾了好一阵才找到靠谱的解决办法。根据你使用的Swagger组件版本，给你两种针对性的方案：

方案一：如果你用的是SpringDoc OpenAPI（Swagger 3.x，推荐） #

这是目前Spring生态下最常用的Swagger集成方式，配置起来很灵活：

方式1：通过配置文件直接指定外部Base URL #

在application.properties（或application.yml）中添加以下配置：

# 后端实际上下文路径，因为代理把/api映射到后端的/
server.servlet.context-path=/

# 指定Swagger UI显示的外部Base URL，本地环境就是你的代理地址
springdoc.swagger-ui.server-url=http://localhost:8082/api

# 保持API文档接口的路径和之前一致
springdoc.api-docs.path=/v2/api-docs

如果是生产环境，建议把springdoc.swagger-ui.server-url改成环境变量占位符（比如${SWAGGER_EXTERNAL_BASE_URL}），避免硬编码。

方式2：用相对路径自动适配环境（更灵活） #

如果不想硬编码地址，可以通过Java配置让Swagger UI自动使用当前页面的访问路径：

import org.springdoc.core.customizers.OpenApiCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.servers.Server;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenApiCustomizer serverUrlCustomizer() {
        return openApi -> {
            openApi.getServers().clear();
            // 添加相对路径/api，Swagger UI会自动拼接当前页面的host和port
            openApi.getServers().add(new Server().url("/api"));
        };
    }
}

这种方式不管是本地测试还是生产部署，都能自动适配代理后的路径，不用修改配置。

方案二：如果你用的是Springfox Swagger 2.x（旧版本） #

如果还在使用传统的Springfox集成，配置方式如下：

方式1：配置文件快速解决 #

在application.properties中添加：

server.servlet.context-path=/
springfox.documentation.swagger.v2.path=/v2/api-docs
# 指定Swagger UI的基础路径，对应代理的/api
springfox.documentation.swagger-ui.base-url=/api

方式2：Java配置自定义Base URL #

如果需要更精细的控制，可以编写Swagger配置类：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger.web.UiConfiguration;
import springfox.documentation.swagger.web.UiConfigurationBuilder;

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.your.project.package"))
                .paths(PathSelectors.any())
                .build()
                // 指定外部访问的Base URL，本地环境就是localhost:8082/api
                .host("localhost:8082/api");
    }

    @Bean
    public UiConfiguration uiConfig() {
        return UiConfigurationBuilder.builder()
                // 设置Swagger UI的基础路径，确保请求都带上/api前缀
                .baseUrl("/api")
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("你的API文档")
                .description("API接口说明")
                .version("1.0")
                .build();
    }
}

额外注意：反向代理的头信息传递 #

不管用哪种方案，都要确保你的反向代理（比如Nginx）正确传递转发头，这样Spring Boot才能正确识别外部请求的路径。以Nginx为例，配置示例：

location /api {
    proxy_pass http://backend_host:port/;
    # 传递必要的转发头
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Port $server_port;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Prefix /api;
}

同时在Spring Boot配置中开启转发头处理：

server.forward-headers-strategy=framework

这样配置后，再访问localhost:8082/api/swagger-ui.html，Swagger UI标题下方的Base URL就会正确显示为http://localhost:8082/api了。

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