dubbo自动生成接口文档

最新推荐文章于 2024-04-08 00:13:48 发布

67号宇航员

最新推荐文章于 2024-04-08 00:13:48 发布

阅读量825

点赞数

文章标签： dubbo java 开发语言

本文链接：https://blog.csdn.net/AAA31321/article/details/128578164

版权

dubbo自动生成接口文档

1、介绍

    本文介绍如何利用smart-doc自动生成dubbo接口文档，以及相关的代码配置；

2、代码

2.1、dubbo接口扫描

smart-doc支持单独去扫描dubbo api或者dubbo provider。在扫描原理是主要通过识别@dubbo注释tag(idea可以支持添加自定义注释tag提示可以参考smart-doc wiki文档介绍)或dubbo的 @service注解。

2.2、扫描dubbo api

dubbo api通常都是很简洁的dubbo接口定义，如果你需要让smart-doc扫描到dubbo接口，那么需要加上@dubbo注释tag。示例如下：
样例
在这里插入图片描述

2.3、扫描dubbo provider

如果想通过dubbo provider生成rpc接口文档的情况，你不需要加任何的其他注释tag，smart-doc自动扫描@service注解完成。
样例
在这里插入图片描述

3、配置文件

3.1、maven配置增加smart-doc-maven-plugin

<plugin>
 <groupId>com.github.shalousun</groupId>
 <artifactId>smart-doc-maven-plugin</artifactId>
 <version>2.1.7</version>
 <configuration>
 <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
 <configFile>./src/main/reources/smart-doc.json</configFile>
 <!--指定项目名称-->
 <projectName>kcb-apps-api</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>

3.2、添加smart-doc所需配置文件

在你的dubbo api或者或者是dubbo provider模块reources中添加smart-doc.json配置文件。
如果下你想让dubbo consumer集成更加快速，你可以将集成配置示例consumer-example.conf中，Smart-doc会将该示例直接输出到文档中。
在这里插入图片描述

smart-doc.json

{
 //是否开启严格模式
 "isStrict": false,
 //是否将文档合并到一个文件中，一般推荐为true
 "allInOne": true,
 //指定文档的输出路径
 "outPath": "D://md2",
 //配置自己的项目名称
 "projectName": "kcb-apps-api",
 // 项目开放的dubbo api接口模块依赖，配置后输出到文档方便使用者集成
 "rpcApiDependencies": [
 {
 "artifactId": "SpringBoot2-Dubbo-Api",
 "groupId": "com.demo",
 "version": "1.0.0"
 }
 ],
 //文档中添加dubbo consumer集成配置，用于方便集成方可以快速集成
 "rpcConsumerConfig": "src/main/resources/consumer-example.conf"

}

consumer-example.conf

dubbo:
 registry:
 protocol: zookeeper
 address: ${zookeeper.adrress}
 id: my-registry
 scan:
 base-packages: com.iflytek.demo.dubbo
 application:
 name: dubbo-consumer