Spring Cloud Gateway API文档集成与展示故障排除-java教程-PHP中文网

Spring Cloud Gateway API文档集成与展示故障排除

霞舞

发布： 2025-11-05 15:08:13

原创

488人浏览过

Spring Cloud Gateway API文档集成与展示故障排除

本文旨在解决spring cloud gateway服务api端点无法通过`springdoc-openapi`（swagger ui或`api-docs`）正常展示的问题。核心解决方案在于正确配置`springdoc`以识别并暴露spring boot actuator的`gateway`端点。通过启用`springdoc.show-actuator`和`management.endpoints.web.exposure.include=gateway`，开发者可以确保gateway路由被`springdoc`发现并集成到api文档中，从而提供完整的服务接口视图。

Spring Cloud Gateway API文档集成与展示

在使用Spring Cloud Gateway作为API网关时，我们通常希望通过springdoc-openapi（或其前身springfox）来自动生成和展示网关所代理的API接口文档。然而，一个常见的问题是，即使配置了springdoc，Gateway自身的路由信息也未能体现在生成的OpenAPI文档（/api-docs）或Swagger UI中，导致paths字段为空。这通常是由于springdoc未能正确识别和暴露Spring Boot Actuator提供的Gateway相关端点所致。

问题分析

当springdoc-openapi在Spring Cloud Gateway应用中运行时，它会尝试扫描并聚合所有可用的API端点。对于标准的Spring Web或Spring WebFlux控制器，这通常是自动完成的。但对于Spring Cloud Gateway定义的路由，其信息是通过Spring Boot Actuator的gateway端点暴露的。如果springdoc没有被明确告知要处理Actuator端点，或者gateway端点本身没有被暴露，那么这些路由信息就无法被捕获。

示例中提供的配置及其响应：

spring:
  cloud:
    gateway:
      routes:
        - id: testapi
          uri: "localhost:8090/api/test/v1"
          predicates:
            - Path=/sa
          filters:
            - AddRequestHeader=secure,true
  application:
    name: gateway-service
server:
  port: 8080
springdoc:
  api-docs:
    path: /api-docs

登录后复制

访问localhost:8080/api-docs时，响应中的paths字段为空，表明Gateway路由并未被springdoc识别。

{
    "openapi": "3.0.1",
    "info": {
        "title": "OpenAPI definition",
        "version": "v0"
    },
    "servers": [
        {
            "url": "http://localhost:8080",
            "description": "Generated server url"
        }
    ],
    "paths": {}, // 路径为空
    "components": {}
}

登录后复制

解决方案

要解决此问题，我们需要在application.yml中添加两个关键配置，以确保springdoc能够发现并处理Gateway的Actuator端点。

集简云

软件集成平台，快速建立企业自动化与智能化

查看详情

启用springdoc对Actuator端点的支持：springdoc.show-actuator=true 这个配置告诉springdoc去扫描并包含Spring Boot Actuator暴露的端点。
暴露gateway Actuator端点：management.endpoints.web.exposure.include=gateway Spring Boot Actuator默认不会暴露所有端点。我们需要明确指定要暴露gateway端点，springdoc才能通过它获取Gateway的路由信息。

完整配置示例

将上述两个配置添加到您的application.yml中，与现有配置合并，如下所示：

spring:
  cloud:
    gateway:
      routes:
        - id: testapi
          uri: "http://localhost:8090/api/test/v1" # 注意：uri通常需要完整协议，例如http://
          predicates:
            - Path=/sa
          filters:
            - AddRequestHeader=secure,true
  application:
    name: gateway-service
server:
  port: 8080

springdoc:
  api-docs:
    path: /api-docs
  # 启用springdoc对Actuator端点的支持
  show-actuator: true

management:
  endpoints:
    web:
      exposure:
        # 暴露gateway Actuator端点
        include: gateway

登录后复制

注意事项：

uri字段在实际应用中通常需要包含协议（如http://或lb://用于负载均衡），否则可能导致路由解析问题。此处已修正为http://localhost:8090/api/test/v1。
management.endpoints.web.exposure.include可以接受逗号分隔的多个端点名称，例如include: health,info,gateway。如果您想暴露所有端点，可以使用include: '*'，但出于安全考虑，这在生产环境中不推荐。
确保您的项目中已引入spring-boot-starter-actuator和springdoc-openapi-starter-webflux-ui（如果使用WebFlux）或springdoc-openapi-starter-webmvc-ui（如果使用WebMVC）。