Dubbo 版 Swagger 来啦！Dubbo-Api-Docs 发布
作者 |?柯然（邪影）
來(lái)源|阿里巴巴云原生公眾號(hào)
背景
Swagger 是一個(gè)規(guī)范和完整的前端框架，用于生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)。Swagger 規(guī)范也逐漸發(fā)展成為了 OpenAPI 規(guī)范。
Springfox 是一個(gè)集成了 Swagger，基于 Sring MVC/Spring Webflux 實(shí)現(xiàn)的一個(gè) Swagger 描述文件生成框架，通過(guò)使用它定義的一些描述接口的注解自動(dòng)生成 Swagger 的描述文件，使 Swagger 能夠展示并調(diào)用接口。
相信很多人都聽(tīng)說(shuō)和使用過(guò) Swagger 和 Springfox，這里就不再贅述了。
Dubbo-Admin 中有接口測(cè)試功能，但是缺少接口描述的文檔，所以該測(cè)試功能比較適合接口開(kāi)發(fā)人員用于測(cè)試接口。而其他人想要使用該功能就必須先通過(guò)接口開(kāi)發(fā)者編寫(xiě)的文檔或者其他方式，了解清楚接口信息才能使用該功能測(cè)試接口。
Dubbo 這邊有沒(méi)有集合文檔展示和測(cè)試功能，可以不用寫(xiě)文檔就能把接口直接給調(diào)用方，類似 Swagger/Springfox 的工具呢？
之前做過(guò)一些調(diào)研，找到一些類似的工具：
- 有些是基于 Springfox 做的，直接一個(gè)文本域放 JSON，與目前 Admin 中的測(cè)試功能大同小異。
- 有些是直接基于 Swagger 的 Java 版 OpenApI 規(guī)范生成工具做的，能把一些基礎(chǔ)數(shù)據(jù)類型的簡(jiǎn)單參數(shù)作為表單項(xiàng)展示。
它們都有一個(gè)共同點(diǎn)：會(huì)把你的提供者變?yōu)?Web 項(xiàng)目。當(dāng)然有些提供者是通過(guò) web 容器加載啟動(dòng)的，甚至也有和 web 工程在一起的，那就無(wú)所謂了。
但也有非 web 的提供者，為了文檔我得把它變?yōu)?web 項(xiàng)目嗎?（還要引入一堆 Web 框架的依賴？比如 Spring MVC？）或者說(shuō)生產(chǎn)環(huán)境打包時(shí)，刪除它的引用和代碼里的相關(guān)注解? 有沒(méi)有簡(jiǎn)單點(diǎn)的方式呢?
OpenAPI 中沒(méi)有 RPC 的規(guī)范，Swagger 是 OpenAPI 的實(shí)現(xiàn)，所以也不支持 RPC 相關(guān)調(diào)用。Springfox 是通過(guò) Swagger 實(shí)現(xiàn)的 RESTful API 的工具，而 RESTful 又是基于 Web 的，Dubbo 沒(méi)法直接使用。我們最終選擇了自己實(shí)現(xiàn)：
- 提供一些描述接口信息的簡(jiǎn)單注解。
- 在提供者啟動(dòng)時(shí)解析注解并緩存解析結(jié)果。
- 在提供者增加幾個(gè) Dubbo-Api-Docs 使用的獲取接口信息的接口。
- 在 Dubbo Admin 側(cè)通過(guò) Dubbo 泛化調(diào)用實(shí)現(xiàn) Http 方式調(diào)用 Dubbo 接口的網(wǎng)關(guān)。
- 在 Dubbo Admin 側(cè)實(shí)現(xiàn)接口信息展示和調(diào)用接口功能。
- 下列情況中的參數(shù)直接展示為表單項(xiàng)，其他的展示為 JSON。
- 方法參數(shù)為基礎(chǔ)數(shù)據(jù)類型的
- 方法參數(shù)為一個(gè) Bean，Bena 中屬性為基礎(chǔ)數(shù)據(jù)類型的
- 很少的第三方依賴，甚至大部分都是你項(xiàng)目里本身就使用的。
- 可以通過(guò) profile 決定是否加載，打包時(shí)簡(jiǎn)單地修改 profile 就能區(qū)分生產(chǎn)和測(cè)試，甚至 profile 你本來(lái)就使用了。
今天，我很高興的宣布：Dubbo 用戶也可以享受類似 Swagger 的體驗(yàn)了 – Dubbo-Api-Docs 發(fā)布了。
簡(jiǎn)介
Dubbo-Api-Docs 是一個(gè)展示 dubbo 接口文檔，測(cè)試接口的工具。
使用 Dubbo-Api-Docs 分為兩個(gè)主要步驟：
在 dubbo 項(xiàng)目引入 Dubbo-Api-Docs 相關(guān) jar 包，并增加類似 Swagger 的注解。
在 Dubbo-Admin 中查看接口描述并測(cè)試。
通過(guò)以上兩個(gè)步驟，即可享受類似 Swagger 的體驗(yàn)，并且可以在生產(chǎn)環(huán)境中關(guān)閉 Dubbo-Api-Docs 的掃描。
Dubbo-Api-Docs 目前通過(guò)直連服務(wù)節(jié)點(diǎn)的方式獲取該服務(wù)的接口列表。測(cè)試接口時(shí)，可以直連也可以通過(guò)注冊(cè)中心，未來(lái)會(huì)增加通過(guò)注冊(cè)中心獲取服務(wù)列表的方式，并根據(jù) Dubbo 的升級(jí)規(guī)劃增加新的功能支持，也會(huì)根據(jù)社區(qū)的需求增加功能。
Dubbo-Api-Docs 會(huì)在服務(wù)提供者啟動(dòng)完畢后，掃描 docs 相關(guān)注解并將處理結(jié)果緩存，并增加一些 Dubbo-Api-Docs 相關(guān)的 Dubbo 提供者接口。緩存的數(shù)據(jù)在將來(lái)可能會(huì)放到 Dubbo 元數(shù)據(jù)中心中。
當(dāng)前版本: 2.7.8.1
<dependency><groupId>org.apache.dubbo</groupId><artifactId>dubbo-api-docs-annotations</artifactId><version>${dubbo-version}</version> </dependency> <dependency><groupId>org.apache.dubbo</groupId><artifactId>dubbo-api-docs-core</artifactId><version>${dubbo-version}</version> </dependency>快速入門
1. dubbo 提供者項(xiàng)目的方法參數(shù)中加上 Dubbo-Api-Docs 注解
- 如果 dubbo 提供者的接口和方法參數(shù)在一個(gè)單獨(dú)的 jar 項(xiàng)目中，則在該項(xiàng)目中引入: dubbo-api-docs-annotations。
- dubbo 提供者項(xiàng)目引入 dubbo-api-docs-core。
- 在提供者項(xiàng)目的項(xiàng)目啟動(dòng)類(標(biāo)注了 @SpringBootApplication 的類)，或者配制類(標(biāo)注了 @Configuration 的類)中增加注解 @EnableDubboApiDocs，以啟用 Dubbo Api Docs 功能。
為避免增加生產(chǎn)環(huán)境中的資源占用，建議單獨(dú)創(chuàng)建一個(gè)配制類用于啟用 Dubbo-Api-Docs，并配合 @Profile(“dev”) 注解使用。>
當(dāng)然，Dubbo-Api-Docs 僅在項(xiàng)目啟動(dòng)時(shí)多消耗了點(diǎn) CPU 資源，并使用了一點(diǎn)點(diǎn)內(nèi)存用于緩存，將來(lái)會(huì)考慮將緩存中的內(nèi)容放到元數(shù)據(jù)中心。
下面以 dubbo-api-docs-examples?項(xiàng)目中的部分服務(wù)接口為例：
git clone -b 2.7.x https://github.com/apache/dubbo-spi-extensions.git進(jìn)入 dubbo-spi-extensions/dubbo-api-docs/dubbo-api-docs-examples 目錄。
dubbo-api-docs-examples 中有兩個(gè)子模塊：
- examples-api：一個(gè) jar 包項(xiàng)目，其中包含服務(wù)的接口和接口參數(shù) Bean。
- examples-provider：提供者服務(wù)端，包含 spring boot 啟動(dòng)器和服務(wù)的實(shí)現(xiàn)。
下面我們?cè)谶@兩個(gè)子模塊中增加 Dubbo-Api-Docs：
examples-api:
maven 引入:
<dependency><groupId>org.apache.dubbo</groupId><artifactId>dubbo-api-docs-annotations</artifactId><version>2.7.8</version> </dependency>org.apache.dubbo.apidocs.examples.params 中有兩個(gè) Bean，我們來(lái)為它們添加 docs 注解。
- QuickStartRequestBean 作為參數(shù) Bean，添加 @RequestParam。
- QuickStartRespBean 作為響應(yīng) Bean，添加 @ResponseProperty。
由于我們只挑選了部分接口作為演示，到此這些接口涉及的 docs 注解添加完畢。
examples-provider:
maven 引入：
<dependency><groupId>org.apache.dubbo</groupId><artifactId>dubbo-api-docs-core</artifactId><version>2.7.8</version> </dependency>我們挑選一個(gè)接口作為演示：
org.apache.dubbo.apidocs.examples.api.impl.QuickStartDemoImpl 中的 quickStart 方法。
QuickStartDemoImpl 實(shí)現(xiàn)了 api 包中的 org.apache.dubbo.apidocs.examples.api.IQuickStartDemo 接口。
- 在 QuickStartDemoImpl 中:
到此 docs 相關(guān)注解已添加完畢，下面我們來(lái)開(kāi)啟 Dubbo-Api-Docs。新增一個(gè)配制類，位置任意，只要能被 spring boot 掃描到就行。
我們?cè)?org.apache.dubbo.apidocs.examples.cfg 包中新增一個(gè)配制類 DubboDocConfig：
@Configuration @Profile("dev") // 配合 Profile 一起使用, 在 profile 為 dev 時(shí)才會(huì)加載該配制類 @EnableDubboApiDocs // 開(kāi)啟 Dubbo-Api-Docs public class DubboDocConfig { }到此 Dubbo-Api-Docs 相關(guān)的東西已經(jīng)添加完畢。
dubbo-api-docs-examples?中有更多更為詳盡的例子，下文中有注解的詳細(xì)說(shuō)明。下面我們來(lái)看一下增加 Dubbo-Api-Docs 后的效果圖：
2. 啟動(dòng)提供者項(xiàng)目
- 示例使用 nacos 作為注冊(cè)中心，下載并啟動(dòng) nacos。
- 在上面的例子中，我們啟動(dòng) examples-provider 項(xiàng)目中的 org.apache.dubbo.apidocs.examples.ExampleApplication。
在 examples-provider 目錄中：
mvn spring-boot:run3. 下載 dubbo-admin
dubbo-admin 倉(cāng)庫(kù)
dubbo-admin 需要下載 develop 分支源碼啟動(dòng)。
git clone -b develop https://github.com/apache/dubbo-admin.git4. 啟動(dòng)訪問(wèn) dubbo-admin
參考 dubbo-admin 里的說(shuō)明啟動(dòng)：
1. 在 dubbo-admin-server/src/main/resources/application.properties 中修改注冊(cè)中心地址 2. 編譯 mvn clean package 3. 啟動(dòng): mvn --projects dubbo-admin-server spring-boot:run 或者 cd dubbo-admin-distribution/target; java -jar dubbo-admin-0.1.jar 4. 瀏覽器訪問(wèn): http://localhost:8080 5. 默認(rèn)帳號(hào)密碼都是: root5. 進(jìn)入"接口文檔"模塊
- 在 “dubbo 提供者 IP” 和 “dubbo提供者端口” 中分別輸入提供者所在機(jī)器 IP 和端口，點(diǎn)擊右側(cè) “加載接口列表” 按鈕。
- 左側(cè)接口列表中加載出接口列表,點(diǎn)擊任意接口，右邊展示出該接口信息及參數(shù)表單。
- 填入表單內(nèi)容后，點(diǎn)擊最下方測(cè)試按鈕。
- 響應(yīng)部分展示了響應(yīng)示例及實(shí)際響應(yīng)結(jié)果。
源碼倉(cāng)庫(kù)
Dubbo-Api-Docs 根據(jù)功能拆分，分別在兩個(gè)倉(cāng)庫(kù)中：
1. dubbo-spi-extensions
dubbo-spi-extensions 倉(cāng)庫(kù)地址
該倉(cāng)庫(kù)存放 dubbo 的一些非核心功能的擴(kuò)展，Dubbo-Api-Docs 作為該倉(cāng)庫(kù)中的一個(gè)子模塊，由于該倉(cāng)庫(kù)屬于 Dubbo 3.0 中規(guī)劃的一部分，而 Dubbo-Api-Docs 是基于 Dubbo 2.7.x 開(kāi)發(fā)的，所以在該倉(cāng)庫(kù)中增加了 2.7.x 分支，Dubbo-Api-Docs 就在該分支下。
?
該倉(cāng)庫(kù)中包含了 Dubbo-Api-Docs 的文檔相關(guān)注解、注解掃描能力和使用示例：
- dubbo-api-docs-annotations：文檔生成的相關(guān)注解。考慮到實(shí)際情況中 dubbo api 的接口類和接口參數(shù)會(huì)規(guī)劃為一個(gè)單獨(dú)的 jar 包，所以注解也獨(dú)立為一個(gè) jar 包。本文后面會(huì)對(duì)注解做詳細(xì)說(shuō)明。
- dubbo-api-docs-core：負(fù)責(zé)解析注解，生成文檔信息并緩存。前面提到的 Dubbo-Api-Docs 相關(guān)接口也在該包中。
- dubbo-api-docs-examples：使用示例。
2. Dubbo-Admin
Dubbo-Admin 倉(cāng)庫(kù)地址
文檔的展示及測(cè)試放在了 dubbo admin 項(xiàng)目中。
注解說(shuō)明
-
@EnableDubboApiDocs：配制注解，啟用 dubbo api docs 功能。
-
@ApiModule：類注解，dubbo 接口模塊信息，用于標(biāo)注一個(gè)接口類模塊的用途。
- value：模塊名稱
- apiInterface：提供者實(shí)現(xiàn)的接口
- version：模塊版本
-
@ApiDoc：方法注解，dubbo 接口信息，用于標(biāo)注一個(gè)接口的用途。
- value：接口名稱
- description：接口描述(可使用 html 標(biāo)簽)
- version：接口版本
- responseClassDescription：響應(yīng)的數(shù)據(jù)的描述
-
@RequestParam：類屬性/方法參數(shù)注解，標(biāo)注請(qǐng)求參數(shù)。
- value：參數(shù)名
- required：是否必傳參數(shù)
- description：參數(shù)描述
- example：參數(shù)示例
- defaultValue：參數(shù)默認(rèn)值
- allowableValues：允許的值，設(shè)置該屬性后界面上將對(duì)參數(shù)生成下拉列表
- 注：使用該屬性后將生成下拉選擇框
- boolean 類型的參數(shù)不用設(shè)置該屬性，將默認(rèn)生成 true/false 的下拉列表
- 枚舉類型的參數(shù)會(huì)自動(dòng)生成下拉列表，如果不想開(kāi)放全部的枚舉值，可以單獨(dú)設(shè)置此屬性
-
@ResponseProperty：類屬性注解，標(biāo)注響應(yīng)參數(shù)。
- value：參數(shù)名
- example：示例
使用注意
- 響應(yīng) bean（接口的返回類型）支持自定義泛型，但只支持一個(gè)泛型占位符。
- 關(guān)于 Map 的使用：Map 的 key 只能用基本數(shù)據(jù)類型。如果 Map 的 key 不是基礎(chǔ)數(shù)據(jù)類型，生成的就不是標(biāo)準(zhǔn) json 格式，會(huì)出異常。
- 接口的同步/異步取自 org.apache.dubbo.config.annotation.Service#async / org.apache.dubbo.config.annotation.DubboService#async。
示例說(shuō)明
dubbo-spi-extensions / Dubbo-Api-Docs?中的 dubbo-api-docs-examples 目錄中為示例工程：
- examples-api：jar 包項(xiàng)目，包含服務(wù)提供者的接口類及參數(shù) Bean。
- examples-provider：使用 dubbo-spring-boot-starter 的提供者項(xiàng)目，注冊(cè)中心使用 nacos。
- examples-provider-sca：使用 spring-cloud-starter-dubbo 的提供者項(xiàng)目，注冊(cè)中心使用 nacos。
示例使用步驟
示例使用 nacos 作為注冊(cè)中心，下載并啟動(dòng) nacos。
任意啟動(dòng) examples-provider 和 examples-provider-sca 中的任意一個(gè)，當(dāng)然也可以兩個(gè)都啟動(dòng)。examples-provider 使用 20881 端口 examples-provider-sca 使用 20882 端口。兩個(gè)項(xiàng)目都是 spring boot 項(xiàng)目，啟動(dòng)類在 org.apache.dubbo.apidocs.examples 包下。
啟動(dòng) Dubbo-Admin，瀏覽器訪問(wèn)：http://localhost:8080。
進(jìn)入 dubbo-admin 中的 “接口文檔” 模塊。
在 “dubbo 提供者 IP” 和 “dubbo 提供者端口” 中分別輸入提供者所在機(jī)器 IP 和端口，點(diǎn)擊右側(cè) “加載接口列表” 按鈕。
左側(cè)接口列表中加載出接口列表，點(diǎn)擊任意接口，右邊展示出該接口信息及參數(shù)表單。
填入表單內(nèi)容后，點(diǎn)擊最下方測(cè)試按鈕。
響應(yīng)部分展示了響應(yīng)示例及實(shí)際響應(yīng)結(jié)果。
如果你對(duì) Dubbo Api Docs 的建設(shè)有興趣，歡迎你釘釘搜索群號(hào)：34403965，加入 Dubbo Api Docs 共建小組；也歡迎你釘釘搜索群號(hào)：21976540，加入 Dubbo 開(kāi)源討論群。
總結(jié)
以上是生活随笔為你收集整理的Dubbo 版 Swagger 来啦！Dubbo-Api-Docs 发布的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。
- 上一篇： ArgoCD + KubeVela：以开
- 下一篇： 人生苦短，开发用云 | 如何优雅完成程序