如何在Kong网关后正确配置Spring OpenAPI UI访问路径

问题原因 #

这个异常的核心原因是SpringDoc OpenAPI默认基于服务自身的上下文路径生成重定向地址、接口文档拉取地址，接入Kong网关后，服务默认感知不到网关侧的/local/api路径前缀，导致生成的地址直接使用了服务自身的/foo上下文路径，缺少了网关前缀。

修复方案 #

方案1：配置X-Forwarded前缀（推荐，适配多环境） #

第一步：修改Kong路由配置，添加转发前缀头

在你现有的kong.yml的foo路由配置中新增请求头转换插件，给后端服务传递网关路径前缀：

services:
 - name: foo
   url: http://localhost:9000/foo
   routes:
   - name: foo-route
     paths:
      - /local/api/foo
     methods:
     - GET
     - POST
     - PUT
     - OPTIONS
     - DELETE
     - PATCH
     - HEAD
     # 新增以下插件配置
     plugins:
     - name: request-transformer
       config:
         add:
           headers:
           - X-Forwarded-Prefix: /local/api/foo

第二步：Spring Boot开启转发头识别

在Spring Boot的application.yml中添加如下配置，让框架识别网关传递的转发头：

server:
  forward-headers-strategy: framework

配置完成后SpringDoc会自动识别X-Forwarded-Prefix头，生成带网关前缀的正确地址，无需硬编码路径。

方案2：硬编码SpringDoc路径前缀（适合固定前缀场景） #

如果不想修改Kong配置，可以直接在Spring Boot中配置SpringDoc的固定路径前缀，修改application.yml：

springdoc:
  swagger-ui:
    config-url: /local/api/foo/v3/api-docs/swagger-config
    url: /local/api/foo/v3/api-docs
  server-url: http://localhost:8000/local/api/foo

也可以通过代码注入自定义OpenAPI Bean实现：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.servers.Server;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SpringDocConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .addServersItem(new Server().url("/local/api/foo"))
                .info(new Info().title("Foo服务接口文档").version("1.0"));
    }
}

验证 #

配置完成后访问http://localhost:8000/local/api/foo/swagger-ui.html，会正常重定向到带/local/api/foo前缀的Swagger UI地址，接口文档可正常加载。

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