手摸手系列之smart-doc兼容zbus最新配置流程

准备食材

zbus版本：1.0.4-SNAPSHOT
smart-doc-maven-plugin插件版本：2.2.6

制作步骤

1. 在需要生成doc文档的接口层pom中，加入smart-doc的插件配置，如图：
   
   加入如下配置：

   <build>
   	<plugins>
   		<plugin>
   			<groupId>com.github.shalousun</groupId>
   			<artifactId>smart-doc-maven-plugin</artifactId>
   			<version>2.2.6</version>
   			<configuration>
   				<!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
   				<configFile>./src/main/java/smart-doc.json</configFile>
   				<!--指定项目名称-->
   				<projectName>测试</projectName>
   				<!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉-->
   				<excludes>
   					<!--格式为：groupId:artifactId;参考如下-->
   					<exclude>com.alibaba:fastjson</exclude>
   				</excludes>
   				<!--自1.0.8版本开始，插件提供includes支持,配置了includes后插件会按照用户配置加载而不是自动加载，因此使用时需要注意-->
   				<!--smart-doc能自动分析依赖树加载所有依赖源码，原则上会影响文档构建效率，因此你可以使用includes来让插件加载你配置的组件-->
   				<includes>
   					<!--格式为：groupId:artifactId;参考如下-->
   					<include>com.alibaba:fastjson</include>
   				</includes>
   			</configuration>
   			<executions>
   				<execution>
   					<!--如果不需要在执行编译时启动smart-doc，则将phase注释掉-->
   					<phase>compile</phase>
   					<goals>
   						<!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
   						<goal>html</goal>
   					</goals>
   				</execution>
   			</executions>
   		</plugin>
   	</plugins>
   </build>
   

   其中configFile标签中路径是你的smart-doc配置文件路径！！

2. 在API层的src/main/java下新增配置文件smart-doc.json
   
   内容如下：

   {
     "serverUrl": "http://127.0.0.1/apply", //服务器地址,非必须。导出postman建议设置成http://{{server}}方便直接在postman直接设置环境变量
     "isStrict": false, //是否开启严格模式
     "allInOne": true,  //是否将文档合并到一个文件中，一般推荐为true
     "outPath": "E://java-docs", //指定文档的输出路径
     "coverOld": true,  //是否覆盖旧的文件，主要用于mardown文件覆盖
     "packageFilters": "com.yorma.apply.api",//controller包过滤，多个包用英文逗号隔开，2.2.2开始需要采用正则：com.test.controller.*
     "projectName": "smart-doc",//配置自己的项目名称
     "framework": "zbus"
   }
   

   其中
   "serverUrl": "http://127.0.0.1/apply"：服务url后面的apply代表接口的根路径，如果你的服务是basic则变为http://127.0.0.1/basic。
   "packageFilters": "com.yorma.apply.api"表示需要扫描的API接口类所在包。
   "outPath": "E://java-docs"指定文档的输出路径。
   更多配置信息，请参考smart-doc官网

3. API接口上确保已经加上了Route注解
   

4. 执行maven的compile或smart-doc插件的html命令来生成文档：
   
   生成的doc文档：
   
   打开文档首页index.html，文档展示如下：
   

总结

so easy!!!
妈妈再也不用担心我不知道某个接口是干嘛的啦~
再也不怕我用错接口啦 ~

技术支持

大佬张哥