smart-doc初体验-springboot生成自动文档

smart-doc初体验

• 一.为什么要引入smart-doc?
• 二.对比swagger
• 三.使用
• 四.讨论
• • 1.设计先行模式
  • 2.代码先行
• 五.体验
• 六.附录
• • 1.完整的配置项:
  • 2.官方地址:

一.为什么要引入smart-doc

1.非侵入式生成接口文档
2.减少接口文档的手动更新麻烦&保证了接口文档和代码的一致
3.随时可生成最新的接口文档
4.保持团队代码风格一致:smart-doc支持javadoc，必须按照这个才能生成有注释的接口文档

二.对比swagger

小结：
swagger
侵入式接口文档生成
每个接口及每个实体类都需要添加注解
配置复杂，需要添加依赖然后需要添加相关配置
编译后自动生成接口文档
需要启动后才能查看，如果配置了安全框架还需要开放相关接口

smart doc
非侵入式接口文档生成
需要按照java文档注释规范对接口及相关对象添加注释
编译文件后需要手动运行插件生成接口文档
配置简单，只需要引入插件，配置文档输出位置即可。相关更加复杂的配置根据需要自行配置。
无需启动项目，生成文档后可直接浏览

smart-doc主要是基于源代码和JAVADOC标注注释来生成文档，是在开发期或者是项目的编译期执行生成文档， 在最终在打包运行的jar内你是找不到smart-doc的依赖的，因此是完全不侵入项目运行期的， 也就不能像swagger一样项目启动时更新文档。

swagger主要原理是利用JAVA的注解和反射机制去生成文档。如果项目文档要比较清晰就必须使用大量的注解。 注解和业务代码强绑定，当然最终构建产出的部署包里也就必须包含swagger的依赖了。也因为swagger是利用反射 来生成文档，所以可以做到项目启动时更新文档

三.使用

1.引入jar包;

          <plugin>
                <groupId>com.github.shalousun</groupId>
                <artifactId>smart-doc-maven-plugin</artifactId>
                <version>2.2.7</version>
                <configuration>
                    <configFile>./src/main/resources/smart-doc.json</configFile>
                    <projectName>Smart-Doc初体验</projectName>
                </configuration>
            </plugin>

2. 配置smart-doc.json

   {

   “serverUrl”: “http://localhost:17150”,
   “outPath”: “src/main/resources/static/doc”,
   “isStrict”: false,
   “#####”: “allInOne:true 此参数表示记录文档变更的记录”,
   “createDebugPage”: false,
   “packageFilters”: “com.it.zqm.controller.*”,
   “style”:“xt256”,
   “showAuthor”:true,
   “inlineEnum”: true,
   “revisionLogs”: [{
   “version”: “文档版本号”,
   “version”: “1.0”,
   “_revisionTime”: “文档修订时间”,
   “revisionTime”: “2020-12-31 10:30”,
   “_status”: “update,create可选”,
   “status”: “update”,
   “author”: “author”,
   “_remarks”: “变更描述”,
   “remarks”: “desc”