在國內dubbo成爲很多互聯網公司高併發分佈式場景下rpc框架的首選,dubbo從開源至今經歷過蠻多的過程,從開源到中間的停止維護,經過三年的沉寂,2017年9月,阿里巴巴宣佈重啓dubbo項目。到2018年2月,阿里將dubbo捐獻給Apache基金會,隨後dubbo經過孵化後順利成爲apache的頂級項目。
當然本文的重點不是介紹dubbo的使用,而是介紹如何利用smart-doc工具來生成dubbo的rpc內部接口文檔。smart-doc因爲其基於註釋和java接口定義自動推導的理念,開源以來受到國內很多開發者的喜愛。在開源之初,smart-doc僅僅支持restful api文檔的生成,但是在發展的過程中,不斷有開發者詢問smart-doc能否支持dubbo rpc接口文檔的生成。經過不斷努力,在smart-doc 1.8.7版本中我們增加了dubbo rpc接口的支持,下面來看看真正的操作。
一、集成smart-doc
smart-doc本着使用簡單的原則開發了maven插件和gradle,通過插件來降低smart-doc的集成難度和去除依賴侵入性。您可以根據自己使用的依賴構建管理工具來選擇相關的插件,下面以使用smart-doc-maven-plugin插件集成smart-doc生成dubbo爲例。當然集成smart-doc來生成dubbo rpc接口文檔你有兩種可選方式:
- 使用smart-doc掃描dubbo api模塊
- 使用smart-doc掃描dubbo provider模塊
下面來看下集成方式。
1.1 添加插件
在你的dubbo api或者或者是dubbo provider模塊中添加smart-doc-maven-plugin。當然你只需要選中一種方式即可
<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配置文件
{
"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文檔
rpcConsumerConfig:
如果下你想讓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註解。
掃描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 | - |
Response-fields:
Field | Type | Description | Since |
---|---|---|---|
uid | String | 用戶id | - |
name | String | 用戶名稱 | - |
address | String | 地址 | - |
使用總結
smart-doc對於dubbo rpc文檔生成的支持比較晚,當然目前市面也沒有比其他比較好的工具以及模板參考。dubbo rpc文檔的這塊還需要更多的用戶提出issue和改進意見。當然如果你認同和喜歡smart-doc請前往項目給我們一些支持點點star。