Spring Cloud Gateway无法访问微服务Swagger文档问题求助

配置信息 #

路由配置 #

搭建Spring Cloud Gateway后，为account-service配置的路由如下：

routes:
  - id: account-service
    uri: lb://account-service
    predicates:
      - Path=/api/v1/account/**

Swagger UI配置 #

Swagger UI的配置：

springdoc:
  swagger-ui:
    urls:
      - name: account
        url: /v3/api-docs/account

分组API定义代码 #

应用中自动生成分组API的代码：

@Bean
public List<GroupedOpenApi> apis() {
    List<GroupedOpenApi> groups = new ArrayList<>();
    List<RouteDefinition> definitions = locator.getRouteDefinitions().collectList().block();
    assert definitions != null;
    definitions.stream().filter(routeDefinition -> routeDefinition.getId().matches(".*-service")).forEach(routeDefinition -> {
        String name = routeDefinition.getId().replaceAll("-service", "");
        System.out.println(name);
        System.out.println(routeDefinition.getUri());
        groups.add(GroupedOpenApi.builder().pathsToMatch("/api/v1/" + name + "/**").group(name).build());
    });
    return groups;
}

错误现象 #

访问account服务的API文档时，页面报错（错误截图：），同时后台抛出以下异常：

2022-08-19 20:04:35.926 ERROR 26989 --- [ctor-http-nio-4] o.s.w.s.adapter.HttpWebHandlerAdapter    : [425c7746-6] 500 Server Error for HTTP GET "/v3/api-docs/document"

java.io.IOException: Connection reset by peer
    at java.base/sun.nio.ch.FileDispatcherImpl.read0(Native Method) ~[na:na]
    Suppressed: reactor.core.publisher.FluxOnAssembly$OnAssemblyException: 
Error has been observed at the following site(s):
    *__checkpoint ⇢ org.springframework.web.cors.reactive.CorsWebFilter [DefaultWebFilterChain]
    *__checkpoint ⇢ org.springframework.cloud.gateway.filter.WeightCalculatorWebFilter [DefaultWebFilterChain]
    *__checkpoint ⇢ HTTP GET "/v3/api-docs/document" [ExceptionHandlingWebHandler]
Original Stack Trace:
        at java.base/sun.nio.ch.FileDispatcherImpl.read0(Native Method) ~[na:na]
        at java.base/sun.nio.ch.SocketDispatcher.read(SocketDispatcher.java:39) ~[na:na]
        at java.base/sun.nio.ch.IOUtil.readIntoNativeBuffer(IOUtil.java:276) ~[na:na]
        at java.base/sun.nio.ch.IOUtil.read(IOUtil.java:233) ~[na:na]
        at java.base/sun.nio.ch.IOUtil.read(IOUtil.java:223) ~[na:na]
        at java.base/sun.nio.ch.SocketChannelImpl.read(SocketChannelImpl.java:356) ~[na:na]
        at io.netty.buffer.PooledByteBuf.setBytes(PooledByteBuf.java:253) ~[netty-buffer-4.1.70.Final.jar:4.1.70.Final]
        at io.netty.buffer.AbstractByteBuf.writeBytes(AbstractByteBuf.java:1132) ~[netty-buffer-4.1.70.Final.jar:4.1.70.Final]
        at io.netty.channel.socket.nio.NioSocketChannel.doReadBytes(NioSocketChannel.java:350) ~[netty-transport-4.1.70.Final.jar:4.1.70.Final]
        at io.netty.channel.nio.AbstractNioByteChannel$NioByteUnsafe.read(AbstractNioByteChannel.java:151) ~[netty-transport-4.1.70.Final.jar:4.1.70.Final]
        at io.netty.channel.nio.NioEventLoop.processSelectedKey(NioEventLoop.java:719) ~[netty-transport-4.1.70.Final.jar:4.1.70.Final]
        at io.netty.channel.nio.NioEventLoop.processSelectedKeysOptimized(NioEventLoop.java:655) ~[netty-transport-4.1.70.Final.jar:4.1.70.Final]
        at io.netty.channel.nio.NioEventLoop.processSelectedKeys(NioEventLoop.java:581) ~[netty-transport-4.1.70.Final.jar:4.1.70.Final]
        at io.netty.channel.nio.NioEventLoop.run(NioEventLoop.java:493) ~[netty-transport-4.1.70.Final.jar:4.1.70.Final]
        at io.netty.util.concurrent.SingleThreadEventExecutor$4.run(SingleThreadEventExecutor.java:986) ~[netty-common-4.1.70.Final.jar:4.1.70.Final]
        at io.netty.util.internal.ThreadExecutorMap$2.run(ThreadExecutorMap.java:74) ~[netty-common-4.1.70.Final.jar:4.1.70.Final]
        at io.netty.util.concurrent.FastThreadLocalRunnable.run(FastThreadLocalRunnable.java:30) ~[netty-common-4.1.70.Final.jar:4.1.70.Final]
        at java.base/java.lang.Thread.run(Thread.java:829) ~[na:na]

问题分析与解决方案 #

核心问题 #

从异常路径/v3/api-docs/document能看出，Swagger UI尝试访问的文档路径错误，实际应为/v3/api-docs/account。根源在于：

1. Gateway缺少转发/v3/api-docs/**路径到对应服务的路由规则；
2. 自动生成的GroupedOpenApi未正确关联服务文档路径，且未修正文档中的服务器地址。

解决步骤 #

1. 添加Gateway路由规则
   在Gateway路由配置中新增API文档转发规则，支持单个服务或通用配置：

   • 单个服务配置：

     routes:
       - id: account-service
         uri: lb://account-service
         predicates:
           - Path=/api/v1/account/**,/v3/api-docs/account
     

   • 通用配置（适配所有服务）：

     routes:
       - id: api-docs-route
         uri: lb://{serviceId}
         predicates:
           - Path=/v3/api-docs/{serviceId}
         filters:
           - SetPath=/v3/api-docs
     

2. 修正GroupedOpenApi配置
   调整代码，确保分组API关联正确路径，并修正文档中的服务器地址：

   @Bean
   public List<GroupedOpenApi> apis(RouteDefinitionLocator locator) {
       List<GroupedOpenApi> groups = new ArrayList<>();
       List<RouteDefinition> definitions = locator.getRouteDefinitions().collectList().block();
       if (definitions == null) {
           return groups;
       }
       definitions.stream()
               .filter(route -> route.getId().matches(".*-service"))
               .forEach(route -> {
                   String serviceId = route.getId().replace("-service", "");
                   groups.add(GroupedOpenApi.builder()
                           .group(serviceId)
                           .pathsToMatch("/api/v1/" + serviceId + "/**")
                           .addOpenApiCustomiser(openApi -> openApi
                                   .servers(List.of(new Server().url("/api/v1/" + serviceId))))
                           .build());
               });
       return groups;
   }
   

3. 验证服务与配置

   • 确认account-service已注册到服务中心，且直接访问服务地址+/v3/api-docs能正常返回文档；
   • 检查springdoc.swagger-ui.urls中的配置路径是否与Gateway路由规则匹配。

内容的提问来源于stack exchange，提问作者Raja T S Sekhar