做者 | 柯然（邪影）html

Dubbo-Api-Docs

背景

Swagger 是一個規範和完整的前端框架,用於生成,描述,調用和可視化 RESTful 風格的 Web 服務. Swagger 規範也逐漸發展成爲了 OpenAPI 規範.前端

Springfox 是一個集成了Swagger,基於 Sring MVC/Spring Webflux 實現的一個 Swagger 描述文件生成框架,經過使用它定義的一些描述接口的註解自動生成Swagger的描述文件, 使 Swagger 可以展現並調用接口.java

相信不少人都據說和使用過Swagger和Springfox, 這裏就再也不贅述了.git

Dubbo-Admin中有接口測試功能,可是缺乏接口描述的文檔,因此該測試功能比較適合接口開發人員用於測試接口.而其餘人想要使用該功能就必須先經過接口開發者編寫的文檔或者其餘方式瞭解清楚接口信息才能使用該功能測試接口. Dubbo這邊有沒有集合文檔展現和測試功能,能不用寫文檔就能把接口直接給調用方,相似Swagger/Springfox的工具呢? 以前作過一些調研,找到一些相似的工具:github

有些是基於Springfox作的,直接一個文本域放JSON, 與目前Admin中的測試功能大同小異
有些是直接基於Swagger的Java版OpenApi規範生成工具作的,能把一些基礎數據類型的簡單參數做爲表單項展現

它們都有一個共同點: 會把你的提供者變爲Web項目. 固然有些提供者是經過web容器加載啓動的,甚至也有和web工程在一塊兒的,那就無所謂了. 但也有非web的提供者. 爲了文檔我得把它變爲web項目嗎?(還要引入一堆Web框架的依賴?好比Spring MVC)或者說生產環境打包時刪除它的引用和代碼裏的相關注解? 有沒有簡單點的方式呢?web

OpenAPI中沒有RPC的規範,Swagger是OpenAPI的實現,因此也不支持RPC相關調用.Springfox是經過Swagger實現的 RESTful API的工具, 而RESTful又是基於Web的,Dubbo無法直接使用.咱們最終選擇了本身實現:spring

提供一些描述接口信息的簡單註解
在提供者啓動時解析註解並緩存解析結果
在提供者增長几個Dubbo-Api-Docs使用的獲取接口信息的接口
在Dubbo Admin側經過Dubbo泛化調用實現Http方式調用Dubbo接口的網關
在Dubbo Admin側實現接口信息展現和調用接口功能
下列狀況中的參數直接展現爲表單項,其餘的展現爲JSON:
- 方法參數爲基礎數據類型的
- 方法參數爲一個Bean,Bena中屬性爲基礎數據類型的
不多的第三方依賴,甚至大部分都是你項目裏自己就使用的
能夠經過profile決定是否加載, 打包時簡單的修改profile就能區分生產和測試,甚至profile你原本就使用了

今天,我很高興的宣佈: Dubbo 用戶也能夠享受相似Swagger的體驗了 -- Dubbo-Api-Docs發佈了.apache

簡介

Dubbo-Api-Docs 是一個展現dubbo接口文檔,測試接口的工具.json

使用 Dubbo-Api-Docs 分爲兩個主要步驟:api

在dubbo項目引入Dubbo-Api-Docs 相關jar包,並增長相似Swagger的註解.
在 Dubbo-Admin 中查看接口描述並測試.

經過以上兩個步驟便可享受相似Swagger的體驗, 而且能夠在生產環境中關閉Dubbo-Api-Docs的掃描.

Dubbo-Api-Docs 目前經過直連服務節點的方式獲取該服務的接口列表. 測試接口時能夠直連也能夠經過註冊中心.將來會增長經過註冊中心獲取服務列表的方式.並根據Dubbo的升級規劃增長新的功能支持.也會根據社區的需求增長功能.

Dubbo-Api-Docs 會在服務提供者啓動完畢後掃描docs相關注解並將處理結果緩存.並增長一些Dubbo-Api-Docs相關的Dubbo提供者接口. 緩存的數據在未來可能會放到Dubbo元數據中心中.

當前版本: 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提供者項目的方法參數中加上 Dubbo-Api-Docs 註解

若是 dubbo提供者的接口和方法參數在一個單獨的jar項目中,則在該項目中引入: dubbo-api-docs-annotations
dubbo提供者項目引入 dubbo-api-docs-core
在提供者項目的項目啓動類(標註了@SpringBootApplication的類)或者配製類(標註了@Configuration的類)中增長註解 @EnableDubboApiDocs 以啓用Dubbo Api Docs功能

爲避免增長生產環境中的資源佔用, 建議單首創建一個配製類用於啓用Dubbo-Api-Docs, 並配合 @Profile("dev") 註解使用固然, Dubbo-Api-Docs 僅在項目啓動時多消耗了點CPU資源, 並使用了一點點內存用於緩存, 未來會考慮將緩存中的內容放到元數據中心.

下面以dubbo-api-docs-examples項目中的部分服務接口爲例:

git clone -b 2.7.x https://github.com/apache/dubbo-spi-extensions.git

進入 dubbo-spi-extensions/dubbo-api-docs/dubbo-api-docs-examples 目錄

dubbo-api-docs-examples 中有兩個子模塊:

examples-api: 一個jar包項目,其中包含服務的接口和接口參數Bean
examples-provider: 提供者服務端,包含spring boot啓動器和服務的實現

下面咱們在這兩個子模塊中增長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 中有兩個Bean,咱們來爲它們添加docs註解

QuickStartRequestBean 做爲參數Bean, 添加 @RequestParam

public class QuickStartRequestBean {

  @RequestParam(value = "You name", required = true, description = "please enter your full name", example = "Zhang San")
  private String name;

  @RequestParam(value = "You age", defaultValue = "18")
  private int age;

  @RequestParam("Are you a main?")
  private boolean man;
  
  // getter/setter略...
}

QuickStartRespBean 做爲響應Bean,添加 @ResponseProperty

public class QuickStartRespBean {

  @ResponseProperty(value = "Response code", example = "500")
  private int code;

  @ResponseProperty("Response message")
  private String msg;

  // getter/setter略...
}

因爲咱們只挑選了部分接口做爲演示,到此這些接口涉及的docs註解添加完畢

examples-provider:

maven引入:

<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo-api-docs-core</artifactId>
    <version>2.7.8</version>
</dependency>

咱們挑選一個接口做爲演示:

org.apache.dubbo.apidocs.examples.api.impl.QuickStartDemoImpl 中的 quickStart 方法

QuickStartDemoImpl 實現了 api包中的 org.apache.dubbo.apidocs.examples.api.IQuickStartDemo 接口

在 QuickStartDemoImpl 中:

@DubboService
@ApiModule(value = "quick start demo", apiInterface = IQuickStartDemo.class, version = "v0.1")
public class QuickStartDemoImpl implements IQuickStartDemo {

  @ApiDoc(value = "quick start demo", version = "v0.1", description = "this api is a quick start demo", responseClassDescription="A quick start response bean")
  @Override
  public QuickStartRespBean quickStart(@RequestParam(value = "strParam", required = true) String strParam, QuickStartRequestBean beanParam) {
    return new QuickStartRespBean(200, "hello " + beanParam.getName() + ", " + beanParam.toString());
  }
}

到此docs相關注解已添加完畢,下面咱們來開啓 Dubbo-Api-Docs. 新增一個配製類,位置任意,只要能被spring boot掃描到就行.

咱們在 org.apache.dubbo.apidocs.examples.cfg 包中新增一個配製類 DubboDocConfig :

@Configuration
@Profile("dev")  // 配合 Profile 一塊兒使用, 在 profile 爲 dev 時纔會加載該配製類
@EnableDubboApiDocs  // 開啓 Dubbo-Api-Docs
public class DubboDocConfig {
}

到此 Dubbo-Api-Docs 相關的東西已經添加完畢. dubbo-api-docs-examples 中有更多更爲詳盡的例子.下文中有註解的詳細說明.下面咱們來看一下增長 Dubbo-Api-Docs 後的效果圖.

2.啓動提供者項目

示例使用nacos做爲註冊中心,下載並啓動nacos
在上面的例子中,咱們啓動 examples-provider 項目中的 org.apache.dubbo.apidocs.examples.ExampleApplication. 在examples-provider目錄中:

mvn spring-boot:run

3.下載 dubbo-admin

dubbo-admin倉庫

dubbo-admin 須要下載 develop 分支源碼啓動
git clone -b develop https://github.com/apache/dubbo-admin.git

4.啓動訪問 dubbo-admin

參考 dubbo-admin 裏的說明啓動:

1. 在 dubbo-admin-server/src/main/resources/application.properties 中修改註冊中心地址
2. 編譯 mvn clean package
3. 啓動: 
mvn --projects dubbo-admin-server spring-boot:run
或者
cd dubbo-admin-distribution/target; java -jar dubbo-admin-0.1.jar
4. 瀏覽器訪問: http://localhost:8080
5. 默認賬號密碼都是: root

5.進入"接口文檔"模塊

在"dubbo提供者IP"和"dubbo提供者端口"中分別輸入提供者所在機器IP和端口, 點擊右側 " 加載接口列表" 按鈕
左側接口列表中加載出接口列表,點擊任意接口,右邊展現出該接口信息及參數表單.
填入表單內容後,點擊最下方測試按鈕
響應部分展現了響應示例及實際響應結果

源碼倉庫

Dubbo-Api-Docs 根據功能拆分,分別在兩個倉庫中:

dubbo-spi-extensions

dubbo-spi-extensions倉庫地址

該倉庫存放dubbo的一些非核心功能的擴展, Dubbo-Api-Docs 做爲該倉庫中的一個子模塊,因爲該倉庫屬於Dubbo 3.0中規劃的一部分,而Dubbo-Api-Docs是基於Dubbo 2.7.x 開發的,因此在該倉庫中增長了2.7.x分支,Dubbo-Api-Docs就在該分支下. 該倉庫中包含了 Dubbo-Api-Docs 的文檔相關注解、註解掃描能力和使用示例:

dubbo-api-docs-annotations: 文檔生成的相關注解.考慮到實際狀況中 dubbo api 的接口類和接口參數會規劃爲一個單獨的jar包, 因此註解也獨立爲一個jar包.本文後面會對註解作詳細說明.
dubbo-api-docs-core: 負責解析註解,生成文檔信息並緩存. 前面提到的Dubbo-Api-Docs相關接口也在該包中
dubbo-api-docs-examples: 使用示例

Dubbo-Admin

Dubbo-Admin倉庫地址

文檔的展現及測試放在了 dubbo admin 項目中

註解說明

@EnableDubboApiDocs: 配製註解, 啓用 dubbo api docs 功能
@ApiModule: 類註解, dubbo接口模塊信息,用於標註一個接口類模塊的用途
- value: 模塊名稱
- apiInterface: 提供者實現的接口
- version: 模塊版本
@ApiDoc: 方法註解, dubbo 接口信息,用於標註一個接口的用途
- value: 接口名稱
- description: 接口描述(可以使用html標籤)
- version: 接口版本
- responseClassDescription: 響應的數據的描述
@RequestParam: 類屬性/方法參數註解,標註請求參數
- value: 參數名
- required: 是否必傳參數
- description: 參數描述
- example: 參數示例
- defaultValue: 參數默認值
- allowableValues: 容許的值,設置該屬性後界面上將對參數生成下拉列表
  - 注:使用該屬性後將生成下拉選擇框
  - boolean 類型的參數不用設置該屬性,將默認生成 true/false 的下拉列表
  - 枚舉類型的參數會自動生成下拉列表,若是不想開放所有的枚舉值,能夠單獨設置此屬性.
@ResponseProperty: 類屬性註解, 標註響應參數
- value: 參數名
- example: 示例

使用注意

響應bean(接口的返回類型)支持自定義泛型, 但只支持一個泛型佔位符
關於Map的使用:Map的key只能用基本數據類型.若是Map的key不是基礎數據類型,生成的就不是標準json格式,會出異常
接口的同步/異步取自 org.apache.dubbo.config.annotation.Service#async / org.apache.dubbo.config.annotation.DubboService#async

示例說明

dubbo-spi-extensions / Dubbo-Api-Docs 中的 dubbo-api-docs-examples 目錄中爲示例工程:

examples-api: jar包項目,包含服務提供者的接口類及參數Bean
examples-provider: 使用 dubbo-spring-boot-starter 的提供者項目, 註冊中心使用 nacos
examples-provider-sca: 使用 spring-cloud-starter-dubbo 的提供者項目, 註冊中心使用 nacos

示例使用步驟

示例使用nacos做爲註冊中心,下載並啓動nacos
任意啓動 examples-provider 和 examples-provider-sca 中的任意一個,固然也能夠兩個都啓動. examples-provider 使用 20881端口 examples-provider-sca 使用20882端口.兩個項目都是spring boot項目,啓動類在 org.apache.dubbo.apidocs.examples 包下.
啓動 Dubbo-Admin, 瀏覽器訪問: http://www.javashuo.com/tag/http://localhost:8080
進入 dubbo-admin 中的 "接口文檔"模塊
在"dubbo提供者IP"和"dubbo提供者端口"中分別輸入提供者所在機器IP和端口, 點擊右側 " 加載接口列表" 按鈕
左側接口列表中加載出接口列表,點擊任意接口,右邊展現出該接口信息及參數表單.
填入表單內容後,點擊最下方測試按鈕
響應部分展現了響應示例及實際響應結果

若是你對 Dubbo Api Docs 的建設有興趣，歡迎你加入 Dubbo Api Docs 共建小組釘釘羣：34403965

也歡迎你加入 Dubbo 開源討論釘釘羣：21976540

Dubbo 版 Swagger 來啦！Dubbo-Api-Docs 發佈