如何生成dubbo rpc接口文档
在国内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。
低调大师中文资讯倾力打造互联网数据资讯、行业资源、电子商务、移动互联网、网络营销平台。
持续更新报道IT业界、互联网、市场资讯、驱动更新,是最及时权威的产业资讯及硬件资讯报道平台。
转载内容版权归作者及来源网站所有,本站原创内容转载请注明来源。
- 上一篇
BaikalDB在同程艺龙的应用实践(二)
本系列文章主要介绍 BaikalDB在同程艺龙的落地实践 作者简介:王勇,同程艺龙架构师,BaikalDB Column Store Contributor,专注于分布式数据库方向的研发工作 欢迎Star关注 BaikalDB (github.com/baidu/BaikalDB) 国内加速镜像库gitee BaikalDB 高性能和扩展性实践 本系列文章把BaikalDB总结为六个核心特性如下图,上篇文章BaikalDB高可用与HTAP特性实践 主要与前两个有关,本篇讨论中间两个, 下篇将讨论最后两个。 这也是我们在业务推广中的关注次序,即 首先必须(Must to)业务场景匹配精 准(1一致性)和运行平稳(2高可用) 其次最好(Had better)是数据多(3扩展性)与跑的快(4高性能) 最后应该是(Should)使用友好(5高兼容性)与 成本节省(6低成本) 简称:稳准多快好省。 本文将会通过介绍业务落地前的两个实际测试案例,来分享总结BaikalDB在性能与扩展性方面的数据。 基于行存OLTP场景的基准测试 测试目标 如果把BaikalDB看成一款产品,基准测试的目的就是加上...
- 下一篇
为什么单元测试不是持续交付的唯一答案
为了让持续集成和持续交付(CI/CD)成为现实,企业必须审查其内部流程,并重新思考如何处理软件交付生命周期。过去的清单和评论根本不是前进的方向。残酷的事实是,大多数企业在持续交付的道路上相当落后。对软件交付过程本身进行根本性的改变与从货架上取下一些工具这样的半个步骤是完全不一样的。 如果目标是对客户和用户做出更好的响应,软件团队需要专注于软件交付周期的更快迭代,并围绕快速响应用户反馈进行组织。虽然可能有如每月发布数量这种代理指标,但采用持续交付的最佳衡量标准是跟踪从反馈到更新软件的时间。 但是如果只是拼凑性地进行持续交付,将无法达成目标。 人们很容易从渐进的角度来看待一个组织如何从现状发展到它想驻足的位置。虽然渐进永远是正确的方法,但目前仅仅迈出第一步的企业不应自欺欺人地认为自己已经走得足够远。 不要依赖于CI/CD工具 通常,团队实行持续交付都是从一些自动化的单元测试来自动化构建过程开始。这是一个很好的开端,但是不要花太多的时间去关注单元测试覆盖的代码行数。相反,企业应该将自动化测试的注意力集中在验证核心业务流程、用户事务和用户交互上,以确保它们仍然按照预期和业务有效运行所需的方式...
相关文章
文章评论
共有0条评论来说两句吧...
文章二维码
点击排行
推荐阅读
最新文章
- CentOS7编译安装Gcc9.2.0,解决mysql等软件编译问题
- Springboot2将连接池hikari替换为druid,体验最强大的数据库连接池
- Docker使用Oracle官方镜像安装(12C,18C,19C)
- 设置Eclipse缩进为4个空格,增强代码规范
- Windows10,CentOS7,CentOS8安装MongoDB4.0.16
- Docker快速安装Oracle11G,搭建oracle11g学习环境
- SpringBoot2配置默认Tomcat设置,开启更多高级功能
- CentOS8安装Docker,最新的服务器搭配容器使用
- SpringBoot2更换Tomcat为Jetty,小型站点的福音
- CentOS7安装Docker,走上虚拟化容器引擎之路