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

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

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

```java
@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 的构建方式。格式如下

```yml
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 配置，<mark>会“自动获取注册服务”里的服务信息</mark>，并生成服务相关的 DocDocket 及对应的 upstream，其中服务名会成为 upstream.target 和 upstream.contextPath，uriPattern 会生成 upstream.uri。


### 4、聚合示例

#### （1）模块服务 appApi


```yaml
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 自动为目标服务名

```yml
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 配置，也可以同时使用）


```yml
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"
```