文档摘要的分布式聚合

接口文档的分布式聚合，可以安排在网关，也可以安排独立的服务。

1、使用 Java 配置类进行构建

在分布式聚合时，DocDocket 配置只需要使用 groupName, basicAuth, upstream 三个配置项。

@Configuration
public class DocConfig {
    @Bean("appApi")
    public DocDocket appApi() {
        return new DocDocket()
                .groupName("app端接口")
                .basicAuth("admin", "1234") //可选（添加 basic auth 验证）
                .upstream("http://demo.com.cn", "/demo", "swagger/v2?group=appApi");
    }
}

upstream 配置时，不要连接自己（否则，可能会死循环），其属性有：

属性	说明
target	目标服务名
uri	接口文档地址
contextPath	文档资源组的上下文路径（在拼接调试地址地用）

contextPath 是为在接口调试时，让程序识别需要调用哪个服务用。

2、两种访问请求

获取接口文档 openapi2-json 的请求

浏览器请求后，框架代理请求 target + uri 获取接口文档（openapi2-json）。

调试接口请求

这是在界面调试时，浏览器会请求 http://localhost:port/{context-path}/{api-path} 。网关程序，通过 context-path 识别服务名并尝试接口调用。如果 api-path 里带有服务名识别的 path 段，则可以不加。

识别服务名后，可通过负载均衡接口 LoadBalance.get("service").getServer() 获取服务地址。再组装出真实的请求地址，转发调试请求。

3、使用 `solon.docs` 配置自动构建（对应的配置结构类为：DocsProperties）

v2.9.1 后支持。使用 solon.docs 配置，可以替代 solon bean 的构建方式。格式如下

solon.docs:
  discover:
    enabled: true
    uriPattern: "swagger/v2?group={service}"  #目标服务的文档接口路径模式（要么带变量 {service}，要么用统一固定值）
    contextPathPattern: "/{service}" #可选 #文档资源组的上下文路径（在拼接调试地址地用）
    syncStatus: false  #同步目标服务上下线状态（如果下线，则文档不显示）
    basicAuth:           #可选
      admin: 1234      
    excludedServices:  #排除目标服务名
      - "xx"
  routes:
     - DocDocket
     - DocDocket

配置项说明：

配置名	说明
discover	自动发现配置
discover.enabled	是否启用自动发现
discover.uriPattern	目标服务的文档接口路径模式，支持`{service}`占位符
discover.contextPathPattern	文档资源组的上下文路径（在拼接调试地址地用），支持`{service}`占位符
discover.syncStatus	同步目标服务上下线状态
discover.basicAuth	添加 basic auth 验证（同时会传递给目标服务的文档摘要）
discover.excludedServices	排除目标服务名

routes	是一个 `Map<String, DocDocket>` 结构，用于配置文档路由（即，手动配置文档）

discover 配置，会“自动获取注册服务”里的服务信息，并生成服务相关的 DocDocket 及对应的 upstream，其中服务名会成为 upstream.target 和 upstream.contextPath，uriPattern 会生成 upstream.uri。

4、聚合示例

（1）模块服务 appApi

solon.app:
  namespace: test
  group: demo
  name: app-api
    
solon.cloud.nacos:
  server: 127.0.0.1:8848   #nacos服务地址

solon.docs: #配置本地文档接口服务
  routes:
     - id: default  #使用固定文档组名（更方便聚合）
       groupName: "app端接口"
       apis: 
         - basePackage: "com.demo.controller.app"

（2）网关服务 doc-gateway （有两种配置方式）

使用发现服务配置。使用发现服务配置后 groupName 自动为目标服务名

solon.app:
  namespace: test
  group: demo
  name: doc-gateway
    
solon.cloud.nacos:
  server: "127.0.0.1:8848"   #以nacos为例
  
solon.docs:
  discover:
     enabled: true
     uriPattern: "swagger/v2?group=default"
     excludedServices: 
       - "self-service-name" #具体的功能服务名

或者，手动本置（routes, discover 配置，也可以同时使用）

solon.app:
  namespace: test
  group: demo
  name: doc-gateway
    
solon.cloud.nacos:
  server: "127.0.0.1:8848"   #以nacos为例
  
solon.docs:
  routes:
     - id: appApi                 # doc group-id
       groupName: "app端接口" # doc group-name
       upstream: 
         target: "lb://app-api"  #使用具体地址，或使用服务名
         contextPath: "/app-api" #可选（没有时，根据 service 自动生成）
         uri: "swagger/v2?group=default"

Solon v2.9.3