![頭圖.png](https://ucc.alicdn.com/pic/developer-ecology/5b649e3f7fbc4889abdcdcf3320706ca.png)

作者 | 柯然（邪影）
來源|[阿里巴巴雲原生公眾號](https://mp.weixin.qq.com/s/Ug1tUcoY9jyBHI1jcqlbIw)

# 背景

Swagger 是一個規範和完整的前端框架，用於生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務。Swagger 規範也逐漸發展成為了 OpenAPI 規範。

Springfox 是一個整合了 Swagger，基於 Sring MVC/Spring Webflux 實現的一個 Swagger 描述檔案生成框架，透過使用它定義的一些描述介面的註解自動生成 Swagger 的描述檔案，使 Swagger 能夠展示並呼叫介面。

相信很多人都聽說和使用過 Swagger 和 Springfox，這裡就不再贅述了。

Dubbo-Admin 中有介面測試功能，但是缺少介面描述的文件，所以該測試功能比較適合介面開發人員用於測試介面。而其他人想要使用該功能就必須先透過介面開發者編寫的文件或者其他方式，瞭解清楚介面資訊才能使用該功能測試介面。

Dubbo 這邊有沒有集合文件展示和測試功能，可以不用寫文件就能把介面直接給呼叫方，類似 Swagger/Springfox 的工具呢？

之前做過一些調研，找到一些類似的工具：

- 有些是基於 Springfox 做的，直接一個文字域放 JSON，與目前 Admin 中的測試功能大同小異。
- 有些是直接基於 Swagger 的 Java 版 OpenApI 規範生成工具做的，能把一些基礎資料型別的簡單引數作為表單項展示。

它們都有一個共同點：會把你的提供者變為 Web 專案。當然有些提供者是透過 web 容器載入啟動的，甚至也有和 web 工程在一起的，那就無所謂了。

但也有非 web 的提供者，為了文件我得把它變為 web 專案嗎?（還要引入一堆 Web 框架的依賴？比如 Spring MVC？）或者說生產環境打包時，刪除它的引用和程式碼裡的相關注解? 有沒有簡單點的方式呢?

OpenAPI 中沒有 RPC 的規範，Swagger 是 OpenAPI 的實現，所以也不支援 RPC 相關呼叫。Springfox 是透過 Swagger 實現的 RESTful API 的工具，而 RESTful 又是基於 Web 的，Dubbo 沒法直接使用。我們最終選擇了自己實現：

- 提供一些描述介面資訊的簡單註解。
- 在提供者啟動時解析註解並快取解析結果。
- 在提供者增加幾個 Dubbo-Api-Docs 使用的獲取介面資訊的介面。
- 在 Dubbo Admin 側透過 Dubbo 泛化呼叫實現 Http 方式呼叫 Dubbo 介面的閘道器。
- 在 Dubbo Admin 側實現介面資訊展示和呼叫介面功能。
- 下列情況中的引數直接展示為表單項，其他的展示為 JSON。
   - 方法引數為基礎資料型別的
   - 方法引數為一個 Bean，Bena 中屬性為基礎資料型別的
- 很少的第三方依賴，甚至大部分都是你專案裡本身就使用的。
- 可以透過 profile 決定是否載入，打包時簡單地修改 profile 就能區分生產和測試，甚至 profile 你本來就使用了。

> **今天，我很高興的宣佈：Dubbo 使用者也可以享受類似 Swagger 的體驗了 -- Dubbo-Api-Docs 釋出了。**

# 簡介

Dubbo-Api-Docs 是一個展示 dubbo 介面文件，測試介面的工具。

使用 Dubbo-Api-Docs 分為兩個主要步驟：

1. 在 dubbo 專案引入 Dubbo-Api-Docs 相關 jar 包，並增加類似 Swagger 的註解。

1. 在 Dubbo-Admin 中檢視介面描述並測試。

透過以上兩個步驟，即可享受類似 Swagger 的體驗，並且可以在生產環境中關閉 Dubbo-Api-Docs 的掃描。

Dubbo-Api-Docs 目前透過直連服務節點的方式獲取該服務的介面列表。測試介面時，可以直連也可以透過註冊中心，未來會增加透過註冊中心獲取服務列表的方式，並根據 Dubbo 的升級規劃增加新的功能支援，也會根據社群的需求增加功能。

Dubbo-Api-Docs 會在服務提供者啟動完畢後，掃描 docs 相關注解並將處理結果快取，並增加一些 Dubbo-Api-Docs 相關的 Dubbo 提供者介面。快取的資料在將來可能會放到 Dubbo 後設資料中心中。

# 當前版本: 2.7.8.1

```xml
<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**](https://github.com/apache/dubbo-spi-extensions/tree/2.7.x/dubbo-api-docs/dubbo-api-docs-examples)** 專案中的部分服務介面為例**：

```bash
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 引入:

```xml
<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。

```java
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。

```java
public class QuickStartRespBean {

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

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

// getter/setter略...
}
```

由於我們只挑選了部分介面作為演示，到此這些介面涉及的 docs 註解新增完畢。

> examples-provider:

maven 引入：

```xml
<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 中:

```java
@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：

```java
@Configuration
@Profile("dev")  // 配合 Profile 一起使用, 在 profile 為 dev 時才會載入該配製類
@EnableDubboApiDocs  // 開啟 Dubbo-Api-Docs
public class DubboDocConfig {
}
```

到此 Dubbo-Api-Docs 相關的東西已經新增完畢。

[dubbo-api-docs-examples](https://github.com/apache/dubbo-spi-extensions/tree/2.7.x/dubbo-api-docs/dubbo-api-docs-examples) 中有更多更為詳盡的例子，下文中有註解的詳細說明。下面我們來看一下增加 Dubbo-Api-Docs 後的效果圖：

![2.png](https://ucc.alicdn.com/pic/developer-ecology/39aaae4779df490c953e98567cc457dd.png)

## 2. 啟動提供者專案

- 示例使用 nacos 作為註冊中心，[下載並啟動 nacos。](https://nacos.io)
- 在上面的例子中，我們啟動 examples-provider 專案中的 org.apache.dubbo.apidocs.examples.ExampleApplication。

在 examples-provider 目錄中：

```bash
mvn spring-boot:run
```

## 3. 下載 dubbo-admin

#### [dubbo-admin 倉庫](https://github.com/apache/dubbo-admin)

> dubbo-admin 需要下載 develop 分支原始碼啟動。

```bash
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 根據功能拆分，分別在兩個倉庫中：

## 1. dubbo-spi-extensions

> #### [dubbo-spi-extensions 倉庫地址](https://github.com/apache/dubbo-spi-extensions)

該倉庫存放 dubbo 的一些非核心功能的擴充套件，Dubbo-Api-Docs 作為該倉庫中的一個子模組，由於該倉庫屬於 Dubbo 3.0 中規劃的一部分，而 Dubbo-Api-Docs 是基於 Dubbo 2.7.x 開發的，所以在該倉庫中增加了 [2.7.x 分支](https://github.com/apache/dubbo-spi-extensions/tree/2.7.x/dubbo-api-docs)，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：使用示例。

## 2. Dubbo-Admin

> #### [Dubbo-Admin 倉庫地址](https://github.com/KeRan213539/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 ](https://github.com/apache/dubbo-spi-extensions/tree/2.7.x/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。

## 示例使用步驟

1. 示例使用 nacos 作為註冊中心，[下載並啟動 nacos。](https://nacos.io)

1. 任意啟動 examples-provider 和 examples-provider-sca 中的任意一個，當然也可以兩個都啟動。examples-provider 使用 20881 埠 examples-provider-sca 使用 20882 埠。兩個專案都是 spring boot 專案，啟動類在 org.apache.dubbo.apidocs.examples 包下。

1. 啟動 [Dubbo-Admin](https://github.com/KeRan213539/dubbo-admin)，瀏覽器訪問：[http://localhost:8080](http://localhost:8080)。

1. 進入 dubbo-admin 中的 “介面文件” 模組。

1. 在 “dubbo 提供者 IP” 和 “dubbo 提供者埠” 中分別輸入提供者所在機器 IP 和埠，點選右側 “載入介面列表” 按鈕。

1. 左側介面列表中載入出介面列表，點選任意介面，右邊展示出該介面資訊及參數列單。

1. 填入表單內容後，點選最下方測試按鈕。

1. 響應部分展示了響應示例及實際響應結果。

如果你對 Dubbo Api Docs 的建設有興趣，歡迎你釘釘搜尋群號：34403965，加入 Dubbo Api Docs 共建小組；也歡迎你釘釘搜尋群號：21976540，加入 Dubbo 開源討論群。

Dubbo 版 Swagger 來啦！Dubbo-Api-Docs 釋出

相關文章