博客

站在巨人的肩膀上寻求项目文档~~~~~~~

原来的项目用过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
}

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

待续~~~~~