在國內dubbo成爲不少互聯網公司高併發分佈式場景下rpc框架的首選，dubbo從開源至今經歷過蠻多的過程，從開源到中間的中止維護，通過三年的沉寂，2017年9月，阿里巴巴宣佈重啓dubbo項目。到2018年2月，阿里將dubbo捐獻給Apache基金會，隨後dubbo通過孵化後順利成爲apache的頂級項目。html

固然本文的重點不是介紹dubbo的使用，而是介紹如何利用smart-doc工具來生成dubbo的rpc內部接口文檔。smart-doc由於其基於註釋和java接口定義自動推導的理念，開源以來受到國內不少開發者的喜好。在開源之初，smart-doc僅僅支持restful api文檔的生成，可是在發展的過程當中，不斷有開發者詢問smart-doc可否支持dubbo rpc接口文檔的生成。通過不斷努力，在smart-doc 1.8.7版本中咱們增長了dubbo rpc接口的支持，下面來看看真正的操做。java

1、集成smart-doc

smart-doc本着使用簡單的原則開發了maven插件和gradle，經過插件來下降smart-doc的集成難度和去除依賴侵入性。您能夠根據本身使用的依賴構建管理工具來選擇相關的插件，下面以使用smart-doc-maven-plugin插件集成smart-doc生成dubbo爲例。固然集成smart-doc來生成dubbo rpc接口文檔你有兩種可選方式：git

使用smart-doc掃描dubbo api模塊
使用smart-doc掃描dubbo provider模塊

下面來看下集成方式。github

1.1 添加插件

在你的dubbo api或者或者是dubbo provider模塊中添加smart-doc-maven-plugin。固然你只須要選中一種方式便可apache

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>[最新版本]</version>
    <configuration>
        <!--指定生成文檔的使用的配置文件,配置文件放在本身的項目中-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定項目名稱-->
        <projectName>測試</projectName>
        <!--smart-doc實現自動分析依賴樹加載第三方依賴的源碼，若是一些框架依賴庫加載不到致使報錯，這時請使用excludes排除掉-->
        <excludes>
            <!--格式爲：groupId:artifactId;參考以下-->
            <!--1.0.7版本開始你還能夠用正則匹配排除,如：poi.* -->
            <exclude>com.alibaba:fastjson</exclude>
        </excludes>
        <!--自1.0.8版本開始，插件提供includes支持-->
        <!--smart-doc能自動分析依賴樹加載全部依賴源碼，原則上會影響文檔構建效率，所以你可使用includes來讓插件加載你配置的組件-->
        <includes>
            <!--格式爲：groupId:artifactId;參考以下-->
            <include>com.alibaba:fastjson</include>
        </includes>
    </configuration>
    <executions>
        <execution>
            <!--若是不須要在執行編譯時啓動smart-doc，則將phase註釋掉-->
            <phase>compile</phase>
            <goals>
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>

添加smart-doc所需配置文件

在你的dubbo api或者或者是dubbo provider模塊reources中添加smart-doc.json配置文件json

{
  "isStrict": false, //是否開啓嚴格模式
  "allInOne": true,  //是否將文檔合併到一個文件中，通常推薦爲true
  "outPath": "D://md2", //指定文檔的輸出路徑
  "projectName": "smart-doc",//配置本身的項目名稱
  "rpcApiDependencies":[{ // 項目開放的dubbo api接口模塊依賴，配置後輸出到文檔方便使用者集成
      "artifactId":"SpringBoot2-Dubbo-Api",
      "groupId":"com.demo",
      "version":"1.0.0"
  }],
  "rpcConsumerConfig":"src/main/resources/consumer-example.conf"//文檔中添加dubbo consumer集成配置，用於方便集成方能夠快速集成
}

關於smart-doc若是你生成文檔須要更詳細的配置請常看官方項目wiki文檔官方wiki文檔api

rpcConsumerConfig：restful

若是下你想讓dubbo consumer集成更加快速，你能夠將集成配置示例consumer-example.conf中，Smart-doc會將該示例直接輸出到文檔中。併發

dubbo:
  registry:
    protocol: zookeeper
    address:  ${zookeeper.adrress}
    id: my-registry
  scan:
    base-packages: com.iflytek.demo.dubbo
  application:
    name: dubbo-consumer

dubbo接口掃描

上面提到了smart-doc支持單獨去掃描dubbo api或者dubbo provider。在掃描原理是主要經過識別@dubbo註釋tag(idea能夠支持添加自定義註釋tag提示能夠參考smart-doc wiki文檔介紹)或dubbo的 @service註解。app

掃描dubbo api

dubbo api一般都是很簡潔的dubbo接口定義，若是你須要讓smart-doc掃描到dubbo接口，那麼須要加上@dubbo註釋tag。示例以下：

/**
 * 用戶操做
 *
 * @author yu 2019/4/22.
 * @author zhangsan 2019/4/22.
 * @version 1.0.0
 * @dubbo
 */
public interface UserService {

    /**
     * 查詢全部用戶
     *
     * @return
     */
    List<User> listOfUser();

    /**
     * 根據用戶id查詢
     *
     * @param userId
     * @return
     */
    User getById(String userId);
}

掃描dubbo provider

若是想經過dubbo provider生成rpc接口文檔的狀況，你不須要加任何的其餘註釋tag，smart-doc自動掃描@service註解完成。

/**
 * @author yu 2019/4/22.
 */
@Service
public class UserServiceImpl implements UserService {

    private static Map<String,User> userMap = new HashMap<>();

    static {
        userMap.put("1",new User()
                .setUid(UUIDUtil.getUuid32())
                .setName("zhangsan")
                .setAddress("四川成都")
        );
    }
    
    /**
     * 獲取用戶
     * @param userId
     * @return
     */
    @Override
    public User getById(String userId) {
        return userMap.get(userId);
    }

    /**
     * 獲取用戶
     * @return
     */
    @Override
    public List<User> listOfUser() {
        return userMap.values().stream().collect(Collectors.toList());
    }
}

生成操做

直接經過maven命令運行插件的文檔生成命令或者在idea中直接單擊插件的可視化命令便可。

dubbo-api文檔生成效果圖

Add dependency

<dependency>
    <groupId>com.demo</groupId>
    <artifactId>SpringBoot2-Dubbo-Api</artifactId>
    <version>1.0.0</version>
</dependency>

<dependency>
    <groupId>com.demo</groupId>
    <artifactId>SpringBoot2-Dubbo-Api</artifactId>
    <version>1.0.0</version>
</dependency>

用戶操做

URI: dubbo://localhost:20880/com.iflytek.demo.dubbo.api.interfaces.UserService

Service: com.iflytek.demo.dubbo.api.interfaces.UserService

Protocol: dubbo

Author: yu 2019/4/22., zhangsan 2019/4/22.

Version: 1.0.0

查詢全部用戶

Definition： List<User> listOfUser()

Description: 查詢全部用戶

Response-fields:

Field	Type	Description	Since
uid	String	用戶id	-
name	String	用戶名稱	-
address	String	地址	-

根據用戶id查詢

Definition： User getById(String userId)

Description: 根據用戶id查詢

Invoke-parameters:

Parameter	Type	Description	Required	Since
userId	String	用戶id	true	-