如何在Swagger UI中统一展示多个微服务的OpenAPI规范？

完全可以不用手动合并OpenAPI的yaml/json文件，利用Quarkus生态的工具就能自动实现多微服务文档的聚合展示，以下是两种最实用的方案：

方案一：使用Quarkus官方OpenAPI聚合扩展 #

Quarkus提供了quarkus-smallrye-openapi-aggregator扩展，专门用于自动拉取并聚合多个微服务的OpenAPI文档，无需手动维护合并文件。

实现步骤： #

1. 新建聚合服务：创建一个空的Quarkus项目（Kotlin/Java均可），作为统一文档的入口。
2. 添加聚合扩展依赖：
   • Maven（pom.xml）：

     <dependency>
         <groupId>io.quarkus</groupId>
         <artifactId>quarkus-smallrye-openapi-aggregator</artifactId>
     </dependency>
     

   • Gradle Kotlin（build.gradle.kts）：

     implementation("io.quarkus:quarkus-smallrye-openapi-aggregator")
     

3. 配置微服务OpenAPI地址：在application.properties中配置所有需要聚合的微服务端点（Quarkus默认OpenAPI路径为/q/openapi），同时给每个服务命名方便识别：

   # 用户服务配置
   quarkus.smallrye-openapi.aggregator.services.user-service.url=http://user-service:8080/q/openapi
   quarkus.smallrye-openapi.aggregator.services.user-service.name=用户服务
   # 订单服务配置
   quarkus.smallrye-openapi.aggregator.services.order-service.url=http://order-service:8080/q/openapi
   quarkus.smallrye-openapi.aggregator.services.order-service.name=订单服务
   

4. 启动聚合服务：访问http://<聚合服务地址>:<端口>/q/swagger-ui，就能看到所有微服务的接口统一展示，每个接口会自动带上所属服务的标签，前端无需关注底层架构。

该方案轻量无侵入，聚合服务仅负责文档拉取与展示；只要微服务的OpenAPI端点可达，就能自动同步最新文档。

方案二：结合API Gateway实现文档聚合与请求路由 #

如果架构已引入或计划引入API Gateway，可以直接在网关中集成OpenAPI聚合，既能统一路由请求，又能统一展示文档，更贴合生产场景。

基于Quarkus Gateway的实现： #

1. 创建Quarkus网关服务，添加网关与OpenAPI依赖：
   • Maven（pom.xml）：

     <dependency>
         <groupId>io.quarkus</groupId>
         <artifactId>quarkus-resteasy-reactive-gateway</artifactId>
     </dependency>
     <dependency>
         <groupId>io.quarkus</groupId>
         <artifactId>quarkus-smallrye-openapi</artifactId>
     </dependency>
     

2. 配置路由规则与聚合开关：在application.properties中设置路由与聚合配置：

   # 路由：/user/** 转发到用户服务
   quarkus.gateway.route.user-service.paths=/user/**
   quarkus.gateway.route.user-service.uri=http://user-service:8080
   # 路由：/order/** 转发到订单服务
   quarkus.gateway.route.order-service.paths=/order/**
   quarkus.gateway.route.order-service.uri=http://order-service:8080
   
   # 开启OpenAPI自动聚合
   quarkus.smallrye-openapi.aggregator.enabled=true
   

3. 启动网关服务：访问http://<网关地址>:<端口>/q/swagger-ui，即可查看所有路由对应的接口，前端还能直接通过网关发起请求，无需知晓微服务地址。

额外注意事项： #

• 确保所有微服务的/q/openapi端点对外可访问；若微服务有认证拦截，可在聚合服务/网关配置中添加认证头，比如quarkus.smallrye-openapi.aggregator.services.<service-name>.headers.Authorization=Bearer <token>。
• 可通过quarkus.smallrye-openapi.aggregator.merge-strategy配置文档合并策略，处理重复Schema定义等场景。

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