Springfox Swagger UI IPv6访问报错：无法推断Base URL问题咨询

已知问题确认 #

Springfox Swagger UI 5.x版本在处理IPv6地址时，确实存在base URL自动推断失效的问题。核心原因是Swagger UI内部解析请求地址时，未正确处理IPv6的标准格式（如带方括号的[xxxx:xxxx:xxxx:xxxx]），导致无法识别服务根路径，进而弹出无法推断base URL的提示。这种问题在网关后部署场景中更明显，因为网关转发的请求头可能未正确传递IPv6地址信息，或Swagger UI无法从中解析出合规的IPv6地址格式。

针对Spring Framework（非Spring Boot）的解决方法 #

由于你未使用Spring Boot，可通过手动配置绕过自动推断逻辑，具体步骤如下：

1. 显式配置Docket的host属性 #

在Swagger的Docket配置Bean中，直接指定包含IPv6地址的服务根路径：

@Bean
public Docket api() {
    return new Docket(DocumentationType.OAS_30)
            .host("[your-ipv6-address]:[port]/api") // 替换为实际IPv6地址、端口和API根路径
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.your.service.package"))
            .paths(PathSelectors.any())
            .build()
            .apiInfo(apiInfo());
}

2. 强制指定Swagger UI的API文档路径 #

如果上述配置无效，可通过注册Swagger UI Servlet时添加初始化参数，直接指定API文档接口路径：

@Bean
public ServletRegistrationBean<SwaggerUiServlet> swaggerUiServlet() {
    ServletRegistrationBean<SwaggerUiServlet> registrationBean = 
        new ServletRegistrationBean<>(new SwaggerUiServlet(), "/api/swagger-ui/*");
    registrationBean.addInitParameter("url", "/api/v3/api-docs"); // 替换为你的API文档接口路径
    return registrationBean;
}

若你自定义了Swagger UI的HTML页面，也可直接修改初始化脚本：

<script>
window.onload = function() {
  const ui = SwaggerUIBundle({
    url: "/api/v3/api-docs",
    dom_id: '#swagger-ui',
    // 保留其他原有配置
  });
}
</script>

3. 检查网关请求头转发配置 #

确保API网关转发IPv6请求时，正确传递X-Forwarded-Host、X-Forwarded-Proto等请求头，且头信息中的IPv6地址带有标准方括号格式。Swagger UI自动推断base URL时依赖这些头信息，若网关未正确传递也会导致推断失败。

额外说明 #

该IPv6相关问题在Springfox 6.x及后续版本中已有部分修复，但针对5.2.0版本，手动指定base URL或API文档路径是最直接的解决方式。

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