Dubbo-Api-Docs 是一個(gè)展示dubbo接口文檔,測(cè)試接口的工具. 參考了springfox的設(shè)計(jì),通過增加一些描述接口及參數(shù)的注解,即可展示具備測(cè)試能力的接口文檔.
Dubbo-Api-Docs 目前通過直連服務(wù)節(jié)點(diǎn)的方式獲取該服務(wù)的接口列表. 測(cè)試接口時(shí)可以直連也可以通過注冊(cè)中心.未來會(huì)增加通過注冊(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ù)在將來可能會(huì)放到Dubbo元數(shù)據(jù)中心中.
涉及的倉庫
Dubbo-Api-Docs 根據(jù)功能拆分,分別在兩個(gè)倉庫中:
dubbo-spi-extensions :
該倉庫存放dubbo的一些非核心功能的擴(kuò)展, Dubbo-Api-Docs 作為該倉庫中的一個(gè)子模塊,由于該倉庫屬于Dubbo 3.0中規(guī)劃的一部分,而Dubbo-Api-Docs是基于Dubbo 2.7.x 開發(fā)的,所以在該倉庫中增加了2.7.x分支,Dubbo-Api-Docs就在該分支下.
該倉庫中包含了 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ì)說明.
- dubbo-api-docs-core: 負(fù)責(zé)解析注解,生成文檔信息并緩存. 前面提到的Dubbo-Api-Docs相關(guān)接口也在該包中
- dubbo-api-docs-examples: 使用示例
Dubbo-Admin
文檔的展示及測(cè)試放在了 dubbo admin 項(xiàng)目中
使用
當(dāng)前版本: 同Dubbo版本號(hào)
由于Dubbo-Api-Docs目前還處于測(cè)試階段,并未發(fā)包到maven中央倉庫,需要自行編譯.編譯方式同大部分java工程編譯方式,此處就不贅述了
<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>
- 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)存用于緩存, 將來會(huì)考慮將緩存中的內(nèi)容放到元數(shù)據(jù)中心.
2 . 啟動(dòng)提供者項(xiàng)目
- 下載 dubbo-admin 下載地址
目前dubb-admin也未發(fā)布包含Dubbo-Api-Docs的版本,需要下載源碼啟動(dòng)
- 啟動(dòng) dubbo-admin
- 訪問: http:// localhost:8080
- 進(jìn)入"接口文檔"模塊
注解說明
- @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)生成下拉列表,如果不想開放全部的枚舉值,可以單獨(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
示例說明
dubbo-spi-extensions / Dubbo-Api-Docs 中的 dubbo-api-docs-examples 目錄中為實(shí)例項(xiàng)目:
- 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
實(shí)例使用步驟
- 下載并啟動(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, 瀏覽器訪問: http:// localhost:8080
- 進(jìn)入 dubbo-admin 中的 "接口文檔"模塊
5: 在"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é)果
頁面截圖
