在国内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.shalousungroupId> <artifactId>smart-doc-maven-pluginartifactId> <version>[最新版本]version> <configuration> <configFile>./src/main/resources/smart-doc.jsonconfigFile> <projectName>测试projectName> <excludes> <exclude>com.alibaba:fastjsonexclude> excludes> <includes> <include>com.alibaba:fastjsoninclude> includes> configuration> <executions> <execution> <phase>compilephase> <goals> <goal>htmlgoal> 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集成配置，用于方便集成方可以快速集成}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-consumerdubbo接口扫描
上面提到了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 listOfUser(); /** * 根据用户id查询 * * @param userId * @return */ User getById(String userId);}扫描dubbo provider
如果想通过dubbo provider生成rpc接口文档的情况，你不需要加任何的其他注释tag，smart-doc自动扫描@service注解完成。
/** * @author yu 2019/4/22. */@Servicepublic class UserServiceImpl implements UserService { private static Map 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 ListlistOfUser() { return userMap.values().stream().collect(Collectors.toList()); }}生成操作
直接通过maven命令运行插件的文档生成命令或者在idea中直接单击插件的可视化命令即可。
# dubbo-api文档生成效果图
Add dependency
<dependency> <groupId>com.demogroupId> <artifactId>SpringBoot2-Dubbo-ApiartifactId> <version>1.0.0version>dependency><dependency> <groupId>com.demogroupId> <artifactId>SpringBoot2-Dubbo-ApiartifactId> <version>1.0.0version>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：ListlistOfUser()
Description: 查询所有用户
Response-fields:
根据用户id查询
Definition：User getById(String userId)
Description: 根据用户id查询
Invoke-parameters:
Response-fields:
使用总结
smart-doc对于dubbo rpc文档生成的支持比较晚，当然目前市面也没有比其他比较好的工具以及模板参考。dubbo rpc文档的这块还需要更多的用户提出issue和改进意见。
