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

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

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

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

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

從文檔網(wǎng)關(guān)的角度（此文講聚合嘛），只需使用 groupName, basicAuth, upstream 三個配置項，就可以接入外部服務(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 驗證）.upstream("http://demo.com.cn", "/demo", "swagger/v2?group=appApi");}
}

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

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

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

3、了解 solon.docs 配置格式自動構(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 配置項是專為聚合便利設(shè)計的，方便通過注冊與發(fā)現(xiàn)服務(wù)聚合文檔。格式說明：

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

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

• discover，只會發(fā)現(xiàn)有請求到的服務(wù)（即，LoadBalance.get(name) 觸發(fā)到的服務(wù)）
• 沒有觸發(fā)到的服務(wù)，可以通過 “included” 進行配置

4、聚合示例

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

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ù)配置（這個簡單，可自動和批量）

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ù)名

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

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" #可選（沒有時，根據(jù) service 自動生成）uri: "swagger/v2?group=default"

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