Spring Gateway中OpenAPI Server URL动态配置问题咨询

问题分析 #

直接访问微服务Swagger时Server URL为实际IP，但通过网关访问集中式文档时显示localhost，导致跨机器部署时无法正常调用服务，核心原因是网关聚合OpenAPI文档时未动态替换服务的Base URL为网关的实际公网地址。

解决方案 #

1. 配置网关公网地址变量 #

在部署网关时，通过环境变量DEPLOYMENT_SERVER传入网关的实际IP或域名（替换默认的localhost），确保所有依赖该变量的配置能动态获取正确地址。

2. 修改SpringDoc配置指定Swagger UI的Server URL #

更新application.yml中的springdoc配置，添加server-url指向网关公网地址，让Swagger UI默认使用该地址发起请求：

springdoc:
  swagger-ui:
    use-root-path: true
    configUrl: /v3/api-docs/swagger-config
    url: /v3/api-docs
    urls:
      - name: users
        url: /v3/api-docs/users-service
    server-url: ${GATEWAY_PUBLIC_URL:http://${DEPLOYMENT_SERVER:localhost}:${server.port}}  # 动态绑定网关地址
  cache:
    disabled: true

3. 自定义OpenApiCustomizer统一替换所有微服务的Server地址 #

创建配置类，通过OpenApiCustomizer修改所有聚合的OpenAPI文档，将原有Server地址替换为网关公网地址：

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

@Configuration
public class OpenApiGatewayConfig {

    @Value("${GATEWAY_PUBLIC_URL:http://${DEPLOYMENT_SERVER:localhost}:${server.port}}")
    private String gatewayPublicUrl;

    @Bean
    public OpenApiCustomizer gatewayServerUrlCustomizer() {
        return openApi -> {
            openApi.getServers().clear();
            Server gatewayServer = new Server();
            gatewayServer.setUrl(gatewayPublicUrl);
            openApi.addServersItem(gatewayServer);
        };
    }
}

4. 确保Eureka实例配置正确 #

确认网关和所有微服务的eureka.instance.preferIpAddress均设为true，保证服务发现时使用IP而非hostname，避免调用时指向localhost：

eureka:
  instance:
    preferIpAddress: true

5. 验证路由配置的正确性 #

检查网关的openapi路由，确保uri使用了正确的网关地址变量，避免硬编码localhost：

routes:
  - id: openapi
    uri: http://${DEPLOYMENT_SERVER:localhost}:${server.port}
    predicates:
      - Path=/v3/api-docs/**
    filters:
      - RewritePath=/v3/api-docs/(?<path>.*), /${path}/v3/api-docs

部署注意事项 #

• 启动网关时，通过环境变量传递实际地址，例如：java -jar gateway-service.jar --DEPLOYMENT_SERVER=192.168.1.100（替换为你的网关IP）
• 如果网关使用域名访问，将DEPLOYMENT_SERVER替换为域名即可

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