大家好,又见面了,我是你们的朋友全栈君。如果您正在找激活码,请点击查看最新教程,关注关注公众号 “全栈程序员社区” 获取激活教程,可能之前旧版本教程已经失效.最新Idea2022.1教程亲测有效,一键激活。
Jetbrains全系列IDE使用 1年只要46元 售后保障 童叟无欺
在国内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。
发布者:全栈程序员-用户IM,转载请注明出处:https://javaforall.cn/183719.html原文链接:https://javaforall.cn
【正版授权,激活自己账号】: Jetbrains全家桶Ide使用,1年售后保障,每天仅需1毛
【官方授权 正版激活】: 官方授权 正版激活 支持Jetbrains家族下所有IDE 使用个人JB账号...