在国内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）