提一嘴Swagger
相信不少的小伙伴都会在日常工作中写API文档，确实这个文档很有必要去写，便于项目的维护，在我们提桶的时候，接盘侠可以轻松地接管我们的项目。说起API文档，我们脑海中想到的就是肯定是Swagger，他以前确实统治了江湖很久，因为他的确很方便，也很智能，但是吧，你写多了总感觉哪里不对劲，是的，他的代码侵入性太强，而且要写大量重复的注释，那我最近在写的一个项目来说，简直是程序员的梦魇。
这只是一个实体类的一部分，还有service、controller的这些注解我就不一一列举了，侵入性太强，注释繁多，而且你在编译以后还是存在于代码中不会被擦除。 于是乎，我有一次在写代码（摸鱼）的时候，偶然发现一个Gitee上的高赞API文档，链接：smart-doc
主角smart-doc
smart-doc是一款同时支持JAVA REST API和Apache Dubbo RPC接口文档生成的工具，划重点了，他还支持Dubbo RPC接口文档，遥想当年，Swagger要想支持Dubbo的话必须要自己修改和拓展，官方是不支持的。于是我就照着官方文档给的案例，去部署生成了一下API文档，真香！
新建smart-doc.json
我们需要新建一个smart-doc.json来写一些配置，我这里也给出一份模板，有需要的铁汁们直接cv改改即可。
{ //服务器地址 "serverUrl": "http://127.0.0.1", //是否用严格模式，严格模式强制检查注释 "isStrict": false, //所有接口文档合并生成到一个文档 "allInOne": true, //文档的输出路径 "outPath": "src/main/resources/static/doc", //指定项目名称，用于显示在文档中 "projectName": "test-smart-doc" } 复制代码
引入依赖
<plugin> <groupId>com.github.shalousun</groupId> <artifactId>smart-doc-maven-plugin</artifactId> <version>2.2.2</version> <configuration> <!--指定生成文档使用的配置文件--> <configFile>./src/main/resources/smart-doc.json</configFile> </configuration> <executions> <execution> <!--不需要在编译项目时自动生成文档可注释phase--> <phase>compile</phase> <goals> <goal>html</goal> </goals> </execution> </executions> </plugin> 复制代码
测试
双击smart-doc即可生成java普通（为了区别于Dubbo）的文档，他的UI界面也不丑，大致长这样。
我们几乎没有写任何注释代码，就自动生成了一个API文档，没有任何侵入性。
smart-doc强在哪？
smart-doc对比传统一哥Swagger究竟有什么不同？
- smart-doc主要是基于源代码和JAVADOC标注注释来生成文档，是在开发期或者是项目的编译期执行生成文档，意味着你是在项目编译完以后你在源码里面是找不到smart-doc的任何依赖的，0侵入性。
- swagger主要原理是利用JAVA的注解和反射机制去生成文档，这种方式侵入性太强。
这也就是为什么我刚刚什么注解都没写，但是依然可以生成合格的API文档，于是乎我马上把Swagger换成了smart-doc，只能说真香，再也不用写@ApiModel这种注解了。
