项⽬中实践smart-doc注释⽂档（⼀）
站在巨⼈的肩膀上寻求项⽬⽂档~~~~~~~
原来的项⽬⽤过swagger，慢慢就成了摆设，注解太多，就放弃了~~~~~
也有些项⽬写到了TAPD上⾯，只是，太懒了，要维护上去，实在不想⼲，哇哈哈~~~~~
现在，应该是在某⼤佬的还是博客中发现了smart-doc开源项⽬，以平时少不了的项⽬注释⽣成⽂档接⼝，感觉挺不错，就抱着试⼀试的态度集成了⼀下，⾃我感觉良好(〃'▽'〃)，还可以养成时刻注释的习惯(*^▽^*)~~~~
特此记录⼀下
1.smart-doc是以插件形式集成到项⽬中，加在需要形成⽂档的项⽬中
以上是项⽬结构，这⾥是把插件放在了某⼀分⽀项⽬中，也就是第⼀个pom中
<!--新增插件-->
<plugin>
<groupId>com.github.shalousun</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>2.2.3</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⽀持，配置了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>
ps：具体也可以去开源项⽬去参考⼀下，有详细的⽂档。
2.加过之后，刷新项⽬，会出现如下效果
maven中会发现出现“1”形式，可以点击任意⼀个⽣成对应的⽂档；以HTML为例，如图：
ps:⽣成过程中，会出现⼀些错误，需要根据实际解决，⼩⽩这⾥遇到的问题是某个类或接⼝是不需要的，就忽略了(@ignore)，当然具体的错误要根据具体需要修改，欢迎补充~~~
3.⽂档开始使⽤（类，⽅法等），以项⽬注释为准
简单介绍⼀些注释，具体可以⾃⾏补脑，
类注释：
/**
* 控制器注释
*
* @author 作者
* @date 时间
* @ignore  忽略不显⽰（如果需要显⽰，则不加）
*/
⽅法注释：
/**
* ⽅法注释
* @param list ⽅法参数
* @return  返回参数
* @ignore  同上
*/
ps：其他注释，⾃⾏补脑~~~~
4.就是第⼆步，⽣成相应的⽂档，只不过这⾥⽣成的⽂档⽐较简陋，查看也相对⿇烦，下⼀篇记录对接开源项⽬，完美结合
补充：
忘记了还有重要的⼀步，项⽬中需要添加smart-doc.json⽂件
⽂件中的配置信息：
{
"serverUrl": "{{server}}/api",//项⽬地址前缀，postman形式可以⽤{{server}}形式
"outPath": "D://md2//test-doc",//保存⽣成地址
"packageFilters": "",//过滤器
"projectName": "接⼝⽂档",//接⼝名称
"appKey": "20211013897901945837060096", // torna平台对接appKey,, @since 2.0.9
"appToken": "fb77ffec2bf04538ae3eff1608536a6e", //torna平台appToken,@since 2.0.9
"secret": "nmG.xT8JC&BVMr&&-5GXjcO7V4<=RxWS",//torna平台secret，@since 2.0.9
"openUrl": "localhost:7700/api",//torna平台地址，填写⾃⼰的私有化部署地址@since 2.0.9  "debugEnvName":"测试环境", //torna测试环境
"debugEnvUrl":"127.0.0.1:8800/api"  //torna
}
注：其他需要的配置，可以⾃⾏补脑了~~~
待续~~~~~

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。