1、分布式接口文檔聚合，是什么？

如果你有 “22” 個(gè)不同的服務(wù)（比如微服務(wù)），每個(gè)服務(wù)都有自己的接口文檔。每個(gè)服務(wù)的文檔各自打開(kāi)，估計(jì)你會(huì)覺(jué)得很麻煩的？

再如果，它們是用 openapi 規(guī)范的?，F(xiàn)在，可以通過(guò)一個(gè)服務(wù)去聚合它們。就是，在一個(gè)地址里，打開(kāi) “22” 個(gè)服務(wù)的接口文檔。

2、認(rèn)識(shí) Solon-Docs

solon-docs，是 solon 的接口文檔解決方案。它通過(guò) DocDocket 申明文檔摘要。支持 swagger 注解，或者 javadoc 注釋，或者別的（可適配）。

從文檔網(wǎng)關(guān)的角度（此文講聚合嘛），只需使用 groupName, basicAuth, upstream 三個(gè)配置項(xiàng)，就可以接入外部服務(wù)的接口文檔：

@Configuration
public class DocConfig {@Bean("appApi")public DocDocket appApi() {return new DocDocket().groupName("app端接口").version("2.0") //可選，默認(rèn)是 2.0.basicAuth("admin", "1234") //可選（添加 basic auth 驗(yàn)證）.upstream("http://demo.com.cn", "/demo", "swagger/v2?group=appApi");}
}

upstream 配置值，切不要連接自己（否則，可能會(huì)死循環(huán)），其屬性有：

屬性	說(shuō)明
service	目標(biāo)服務(wù)名
contextPath	服務(wù)上下文路徑（在網(wǎng)關(guān)處，方便識(shí)別是哪個(gè)服務(wù)的，進(jìn)而調(diào)用）
uri	接口文檔地址

solon-docs 也可以通過(guò) solon.docs 配置，完成 DocDocket 自動(dòng)構(gòu)建。

3、了解 solon.docs 配置格式自動(dòng)構(gòu)建

使用 solon.docs 配置，可以替代 solon bean 的構(gòu)建方式。格式如下

solon.docs:discover:uriPattern: "swagger/v2?group={service}"  #目標(biāo)服務(wù)的文檔接口路徑模式（要么帶變量 {service}，要么用統(tǒng)一固定值）syncStatus: false  #同步目標(biāo)服務(wù)上下線狀態(tài)（如果下線，則文檔不顯示）basicAuth:           #可選admin: 1234      excluded:  #排除目標(biāo)服務(wù)名- "xx"included:  #包括目標(biāo)服務(wù)名- "yy"routes:name1: DocDocketname2: DocDocket

discover 配置項(xiàng)是專(zhuān)為聚合便利設(shè)計(jì)的，方便通過(guò)注冊(cè)與發(fā)現(xiàn)服務(wù)聚合文檔。格式說(shuō)明：

配置名	說(shuō)明
discover	用于配置分布式發(fā)現(xiàn)服務(wù)相關(guān)的（即，自動(dòng)配置文檔）
discover.uriPattern	目標(biāo)服務(wù)的文檔接口路徑模式，支持{service}占位符
discover.syncStatus	同步目標(biāo)服務(wù)上下線狀態(tài)
discover.basicAuth	添加 basic auth 驗(yàn)證（同時(shí)會(huì)傳遞給目標(biāo)服務(wù)的文檔摘要）
discover.excluded	排除目標(biāo)服務(wù)名
discover.included	包括目標(biāo)服務(wù)名
routes	是一個(gè) Map<String, DocDocket> 結(jié)構(gòu)，用于配置文檔路由（即，手動(dòng)配置文檔）

discover 配置，會(huì)自動(dòng)生成服務(wù)相關(guān)的 DocDocket 及對(duì)應(yīng)的 upstream，其中服務(wù)名會(huì)成為 upstream.service 和 upstream.contextPath，uriPattern 會(huì)生成 upstream.uri。

• discover，只會(huì)發(fā)現(xiàn)有請(qǐng)求到的服務(wù)（即，LoadBalance.get(name) 觸發(fā)到的服務(wù)）
• 沒(méi)有觸發(fā)到的服務(wù)，可以通過(guò) “included” 進(jìn)行配置

4、聚合示例

（1）模塊服務(wù) app-api （當(dāng)它是 22 個(gè)服務(wù)中的某個(gè)了）

solon.app:namespace: testgroup: demoname: app-apisolon.cloud.nacos:server: "127.0.0.1:8848"   #nacos服務(wù)地址solon.docs: #配置本地文檔接口服務(wù)routes:default:  #使用固定文檔組名（更方便聚合）groupName: "app端接口"apis: - basePackage: "com.demo.controller.app"

（2）文檔網(wǎng)關(guān)服務(wù) doc-gateway （有兩種配置方式）

使用發(fā)現(xiàn)服務(wù)配置（這個(gè)簡(jiǎn)單，可自動(dòng)和批量）

solon.app:namespace: testgroup: demoname: doc-gatewaysolon.cloud.nacos:server: "127.0.0.1:8848"   #nacos服務(wù)地址solon.docs:discover:uriPattern: "swagger/v2?group=default"included: - "app-api" #具體的功能服務(wù)名

或者，手動(dòng)本置（routes, discover 配置，也可以同時(shí)使用）

solon.app:namespace: testgroup: demoname: doc-gatewaysolon.cloud.nacos:server: "127.0.0.1:8848"   #nacos服務(wù)地址solon.docs:routes:appApi:                 # doc group-idgroupName: "app端接口" # doc group-nameupstream: service: "app-api"  #使用具體地址，或使用服務(wù)名contextPath: "/app-api" #可選（沒(méi)有時(shí)，根據(jù) service 自動(dòng)生成）uri: "swagger/v2?group=default"

更多內(nèi)容，可參考 Solon 官網(wǎng)。