共计 4142 个字符，预计需要花费 11 分钟才能阅读完成。
在国内 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. /@Servicepublic 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 接口生成文档了
dubbo-api 文档生成效果图
Add dependency
dubbo: registry: protocol: zookeeper address: ${zookeeper.adrress} id: my-registry scan: base-packages: com.iflytek.demo.dubbo application: name: dubbo-consumer
用户操作
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:
牛皮啊！居然能够为 Dubbo 接口生成文档了
依据用户 id 查问
Definition：User getById(String userId)
Description: 依据用户 id 查问
Invoke-parameters:
牛皮啊！居然能够为 Dubbo 接口生成文档了
Response-fields:
牛皮啊！居然能够为 Dubbo 接口生成文档了
应用总结
smart-doc 对于 dubbo rpc 文档生成的反对比拟晚，当然目前市面也没有比其余比拟好的工具以及模板参考。dubbo rpc 文档的这块还须要更多的用户提出 issue 和改良意见。当然如果你认同和喜爱 smart-doc 请返回我的项目给咱们一些反对点点 star。
如果本文对你有帮忙，别忘记给我个 3 连，点赞，转发，评论，
咱们下期见！学习更多 JAVA 常识与技巧，关注与私信博主（666）
