项目中实践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.就是第二步,生成相应的文档,只不过这里生成的文档比较简陋,查看也相对麻烦,下一篇记录对接Torna开源项目,完美结合

补充:

忘记了还有重要的一步,项目中需要添加smart-doc.json文件

 文件中的配置信息:

{
  "serverUrl": "http://{{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": "http://localhost:7700/api",//torna平台地址,填写自己的私有化部署地址@since 2.0.9
  "debugEnvName":"测试环境", //torna测试环境
  "debugEnvUrl":"http://127.0.0.1:8800/api"   //torna
}

 注:其他需要的配置,可以自行补脑了~~~

待续~~~~~

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值