Swagger 規(guī)范也逐漸發(fā)展成為了 OpenAPI 規(guī)范

作者 | 柯然（邪影）
來源|阿里巴巴云原生公眾號
背景

Swagger 是一個規(guī)范和完整的前端框架，用于生成、描述、調(diào)用和可視化 RESTful 風格的 Web 服務(wù)。Swagger 規(guī)范也逐漸發(fā)展成為了 OpenAPI 規(guī)范。

Springfox 是一個集成了 Swagger，基于 Sring MVC/Spring Webflux 實現(xiàn)的一個 Swagger 描述文件生成框架，通過使用它定義的一些描述接口的注解自動生成 Swagger 的描述文件，使 Swagger 能夠展示并調(diào)用接口。

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

Dubbo-Admin 中有接口測試功能，但是缺少接口描述的文檔，所以該測試功能比較適合接口開發(fā)人員用于測試接口。而其他人想要使用該功能就必須先通過接口開發(fā)者編寫的文檔或者其他方式，了解清楚接口信息才能使用該功能測試接口。

Dubbo 這邊有沒有集合文檔展示和測試功能，可以不用寫文檔就能把接口直接給調(diào)用方，類似 Swagger/Springfox 的工具呢？

 之前做過一些調(diào)研，找到一些類似的工具：

    有些是基于 Springfox 做的，直接一個文本域放 JSON，與目前 Admin 中的測試功能大同小異。
    有些是直接基于 Swagger 的 Java 版 OpenApI 規(guī)范生成工具做的，能把一些基礎(chǔ)數(shù)據(jù)類型的簡單參數(shù)作為表單項展示。

它們都有一個共同點：會把你的提供者變?yōu)?Web 項目。當然有些提供者是通過 web 容器加載啟動的，甚至也有和 web 工程在一起的，那就無所謂了。

但也有非 web 的提供者，為了文檔我得把它變?yōu)?web 項目嗎?（還要引入一堆 Web 框架的依賴？比如 Spring MVC？）或者說生產(chǎn)環(huán)境打包時，刪除它的引用和代碼里的相關(guān)注解? 有沒有簡單點的方式呢?

OpenAPI 中沒有 RPC 的規(guī)范，Swagger 是 OpenAPI 的實現(xiàn)，所以也不支持 RPC 相關(guān)調(diào)用。Springfox 是通過 Swagger 實現(xiàn)的 RESTful API 的工具，而 RESTful 又是基于 Web 的，Dubbo 沒法直接使用。我們最終選擇了自己實現(xiàn)：

    提供一些描述接口信息的簡單注解。
    在提供者啟動時解析注解并緩存解析結(jié)果。
    在提供者增加幾個 Dubbo-Api-Docs 使用的獲取接口信息的接口。
    在 Dubbo Admin 側(cè)通過 Dubbo 泛化調(diào)用實現(xiàn) Http 方式調(diào)用 Dubbo 接口的網(wǎng)關(guān)。
    在 Dubbo Admin 側(cè)實現(xiàn)接口信息展示和調(diào)用接口功能。
    下列情況中的參數(shù)直接展示為表單項，其他的展示為 JSON。
        方法參數(shù)為基礎(chǔ)數(shù)據(jù)類型的
        方法參數(shù)為一個 Bean，Bena 中屬性為基礎(chǔ)數(shù)據(jù)類型的
    很少的第三方依賴，甚至大部分都是你項目里本身就使用的。
    可以通過 profile 決定是否加載，打包時簡單地修改 profile 就能區(qū)分生產(chǎn)和測試，甚至 profile 你本來就使用了。

    今天，我很高興的宣布：Dubbo 用戶也可以享受類似 Swagger 的體驗了 -- Dubbo-Api-Docs 發(fā)布了。

簡介

Dubbo-Api-Docs 是一個展示 dubbo 接口文檔，測試接口的工具。

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

    在 dubbo 項目引入 Dubbo-Api-Docs 相關(guān) jar 包，并增加類似 Swagger 的注解。

    在 Dubbo-Admin 中查看接口描述并測試。

通過以上兩個步驟，即可享受類似 Swagger 的體驗，并且可以在生產(chǎn)環(huán)境中關(guān)閉 Dubbo-Api-Docs 的掃描。

Dubbo-Api-Docs 目前通過直連服務(wù)節(jié)點的方式獲取該服務(wù)的接口列表。測試接口時，可以直連也可以通過注冊中心，未來會增加通過注冊中心獲取服務(wù)列表的方式，并根據(jù) Dubbo 的升級規(guī)劃增加新的功能支持，也會根據(jù)社區(qū)的需求增加功能。

Dubbo-Api-Docs 會在服務(wù)提供者啟動完畢后，掃描 docs 相關(guān)注解并將處理結(jié)果緩存，并增加一些 Dubbo-Api-Docs 相關(guān)的 Dubbo 提供者接口。緩存的數(shù)據(jù)在將來可能會放到 Dubbo 元數(shù)據(jù)中心中。
當前版本: 2.7.8.1

<dependency>
    <groupId>org.apache.dubbo</groupId>
    <artifactId>dubbo-api-docs-annotations</artifactId>
    <version>${dubbo-version}

org.apache.dubbodubbo-api-docs-core${dubbo-version}</version>
</dependency>

    1
    2
    3
    4
    5
    6

快速入門
1. dubbo 提供者項目的方法參數(shù)中加上 Dubbo-Api-Docs 注解

    如果 dubbo 提供者的接口和方法參數(shù)在一個單獨的 jar 項目中，則在該項目中引入: dubbo-api-docs-annotations。
    dubbo 提供者項目引入 dubbo-api-docs-core。
    在提供者項目的項目啟動類(標注了 @SpringBootApplication 的類)，或者配制類(標注了 @Configuration 的類)中增加注解 @EnableDubboApiDocs，以啟用 Dubbo Api Docs 功能。

    為避免增加生產(chǎn)環(huán)境中的資源占用，建議單獨創(chuàng)建一個配制類用于啟用 Dubbo-Api-Docs，并配合 @Profile("dev") 注解使用。>
    當然，Dubbo-Api-Docs 僅在項目啟動時多消耗了點 CPU 資源，并使用了一點點內(nèi)存用于緩存，將來會考慮將緩存中的內(nèi)容放到元數(shù)據(jù)中心。

下面以 dubbo-api-docs-examples 項目中的部分服務(wù)接口為例：

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 包項目，其中包含服務(wù)的接口和接口參數(shù) Bean。
    examples-provider：提供者服務(wù)端，包含 spring boot 啟動器和服務(wù)的實現(xiàn)。

下面我們在這兩個子模塊中增加 Dubbo-Api-Docs：

    examples-api:

maven 引入:

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

    1
    2
    3
    4

org.apache.dubbo.apidocs.examples.params 中有兩個 Bean，我們來為它們添加 docs 注解。

    QuickStartRequestBean 作為參數(shù) 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略...
}

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12

    QuickStartRespBean 作為響應(yīng) Bean，添加 @ResponseProperty。

public class QuickStartRespBean {

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

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

  // getter/setter略...
}

    1
    2
    3
    4
    5
    6
    7
    8
    9

由于我們只挑選了部分接口作為演示，到此這些接口涉及的 docs 注解添加完畢。

    examples-provider:

maven 引入：

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

    1
    2
    3
    4

我們挑選一個接口作為演示：

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

QuickStartDemoImpl 實現(xiàn)了 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());
  }
}

    1
    2
    3
    4
    5
    6
    7
    8
    9

到此 docs 相關(guān)注解已添加完畢，下面我們來開啟 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 {
}

    1
    2
    3
    4

到此 Dubbo-Api-Docs 相關(guān)的東西已經(jīng)添加完畢。

dubbo-api-docs-examples 中有更多更為詳盡的例子，下文中有注解的詳細說明。下面我們來看一下增加 Dubbo-Api-Docs 后的效果圖：

2.png
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

    1
    2
    3
    4
    5
    6
    7

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

    在 “dubbo 提供者 IP” 和 “dubbo提供者端口” 中分別輸入提供者所在機器 IP 和端口，點擊右側(cè) “加載接口列表” 按鈕。
    左側(cè)接口列表中加載出接口列表,點擊任意接口，右邊展示出該接口信息及參數(shù)表單。
    填入表單內(nèi)容后，點擊最下方測試按鈕。
    響應(yīng)部分展示了響應(yīng)示例及實際響應(yīng)結(jié)果。

源碼倉庫

Dubbo-Api-Docs 根據(jù)功能拆分，分別在兩個倉庫中：
1. dubbo-spi-extensions

    dubbo-spi-extensions 倉庫地址

該倉庫存放 dubbo 的一些非核心功能的擴展，Dubbo-Api-Docs 作為該倉庫中的一個子模塊，由于該倉庫屬于 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)注解?？紤]到實際情況中 dubbo api 的接口類和接口參數(shù)會規(guī)劃為一個單獨的 jar 包，所以注解也獨立為一個 jar 包。本文后面會對注解做詳細說明。
    dubbo-api-docs-core：負責解析注解，生成文檔信息并緩存。前面提到的 Dubbo-Api-Docs 相關(guān)接口也在該包中。
    dubbo-api-docs-examples：使用示例。

2. Dubbo-Admin

    Dubbo-Admin 倉庫地址

文檔的展示及測試放在了 dubbo admin 項目中。
注解說明

    @EnableDubboApiDocs：配制注解，啟用 dubbo api docs 功能。

    @ApiModule：類注解，dubbo 接口模塊信息，用于標注一個接口類模塊的用途。
        value：模塊名稱
        apiInterface：提供者實現(xiàn)的接口
        version：模塊版本

    @ApiDoc：方法注解，dubbo 接口信息，用于標注一個接口的用途。
        value：接口名稱
        description：接口描述(可使用 html 標簽)
        version：接口版本
        responseClassDescription：響應(yīng)的數(shù)據(jù)的描述

    @RequestParam：類屬性/方法參數(shù)注解，標注請求參數(shù)。
        value：參數(shù)名
        required：是否必傳參數(shù)
        description：參數(shù)描述
        example：參數(shù)示例
        defaultValue：參數(shù)默認值
        allowableValues：允許的值，設(shè)置該屬性后界面上將對參數(shù)生成下拉列表
            注：使用該屬性后將生成下拉選擇框
            boolean 類型的參數(shù)不用設(shè)置該屬性，將默認生成 true/false 的下拉列表
            枚舉類型的參數(shù)會自動生成下拉列表，如果不想開放全部的枚舉值，可以單獨設(shè)置此屬性

    @ResponseProperty：類屬性注解，標注響應(yīng)參數(shù)。
        value：參數(shù)名
        example：示例

使用注意

    響應(yīng) bean（接口的返回類型）支持自定義泛型，但只支持一個泛型占位符。
    關(guān)于 Map 的使用：Map 的 key 只能用基本數(shù)據(jù)類型。如果 Map 的 key 不是基礎(chǔ)數(shù)據(jù)類型，生成的就不是標準 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 包項目，包含服務(wù)提供者的接口類及參數(shù) 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://localhost:8080。

    進入 dubbo-admin 中的 “接口文檔” 模塊。

    在 “dubbo 提供者 IP” 和 “dubbo 提供者端口” 中分別輸入提供者所在機器 IP 和端口，點擊右側(cè) “加載接口列表” 按鈕。

    左側(cè)接口列表中加載出接口列表，點擊任意接口，右邊展示出該接口信息及參數(shù)表單。

    填入表單內(nèi)容后，點擊最下方測試按鈕。

    響應(yīng)部分展示了響應(yīng)示例及實際響應(yīng)結(jié)果。
————————————————
版權(quán)聲明：本文為CSDN博主「阿里云開發(fā)者」的原創(chuàng)文章，遵循CC 4.0 BY-SA版權(quán)協(xié)議，轉(zhuǎn)載請附上原文出處鏈接及本聲明。
原文鏈接：https://blog.csdn.net/alitech2017/article/details/113523082