🎉 分布式接口文档聚合，Solon 是怎么做的？

[100+ 重磅嘉宾出席 GOTC 2024！ 499 专业观众票 【限时免费】![](https://doc.xiqi.site/media/202408/2024-08-10_100105_5932870.17174019779187744.png)](https://qaxb95n3g50.feishu.cn/share/base/form/shrcntXjImLZ2L4HsDtd976XXmh)

如果你有 “22” 个不同的服务（比如微服务），每个服务都有自己的接口文档。每个服务的文档各自打开，估计你会觉得很麻烦的？

再如果，它们是用 openapi 规范的。现在，可以通过一个服务去聚合它们。就是，在一个地址里，打开 “22” 个服务的接口文档。

### 2、认识 Solon-Docs

solon-docs，是 solon 的接口文档解决方案。它通过 DocDocket 申明文档摘要。支持 swagger 注解，或者 javadoc 注释，或者别的（可适配）。

从文档网关的角度（此文讲聚合嘛），只需使用 groupName, basicAuth, upstream 三个配置项，就可以接入外部服务的接口文档：

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

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

| 属性 | 说明 |
| --- | --- |
| service | 目标服务名 |
| contextPath | 服务上下文路径（在网关处，方便识别是哪个服务的，进而调用） |
| uri | 接口文档地址 |

solon-docs 也可以通过 `solon.docs` 配置，完成 DocDocket 自动构建。

### 3、了解 `solon.docs` 配置格式自动构建

使用 `solon.docs` 配置，可以替代 solon bean 的构建方式。格式如下

```yaml
solon.docs: discover: uriPattern: "swagger/v2?group={service}" #目标服务的文档接口路径模式（要么带变量 {service}，要么用统一固定值） syncStatus: false #同步目标服务上下线状态（如果下线，则文档不显示） basicAuth: #可选 admin: 1234 excluded: #排除目标服务名 - "xx" included: #包括目标服务名 - "yy" routes: name1: DocDocket name2: DocDocket
```

discover 配置项是专为聚合便利设计的，方便通过注册与发现服务聚合文档。格式说明：

| 配置名 | 说明 |
| --- | --- |
| discover | 用于配置分布式发现服务相关的（即，自动配置文档） |
| discover.uriPattern | 目标服务的文档接口路径模式，支持`{service}`占位符 |
| discover.syncStatus | 同步目标服务上下线状态 |
| discover.basicAuth | 添加 basic auth 验证（同时会传递给目标服务的文档摘要） |
| discover.excluded | 排除目标服务名 |
| discover.included | 包括目标服务名 |
|   |   |
| routes | 是一个 `Map<String, DocDocket>` 结构，用于配置文档路由（即，手动配置文档） |

discover 配置，会自动生成服务相关的 DocDocket 及对应的 upstream，其中服务名会成为 upstream.service 和 upstream.contextPath，uriPattern 会生成 upstream.uri。

-   discover，只会发现有请求到的服务（即，LoadBalance.get(name) 触发到的服务）
-   没有触发到的服务，可以通过 "included" 进行配置

### 4、聚合示例

#### （1）模块服务 app-api （当它是 22 个服务中的某个了）

```yaml
solon.app: namespace: test group: demo name: app-api solon.cloud.nacos: server: "127.0.0.1:8848" #nacos服务地址 solon.docs: #配置本地文档接口服务 routes: default: #使用固定文档组名（更方便聚合） groupName: "app端接口" apis: - basePackage: "com.demo.controller.app"
```

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

使用发现服务配置（这个简单，可自动和批量）

```yaml
solon.app: namespace: test group: demo name: doc-gateway solon.cloud.nacos: server: "127.0.0.1:8848" #nacos服务地址 solon.docs: discover: uriPattern: "swagger/v2?group=default" included: - "app-api" #具体的功能服务名
```

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

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

更多内容，可参考 Solon 官网。