提一嘴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究竟有什么不同？

1. smart-doc主要是基于源代码和JAVADOC标注注释来生成文档，是在开发期或者是项目的编译期执行生成文档，意味着你是在项目编译完以后你在源码里面是找不到smart-doc的任何依赖的，0侵入性。
2. swagger主要原理是利用JAVA的注解和反射机制去生成文档，这种方式侵入性太强。

    这也就是为什么我刚刚什么注解都没写，但是依然可以生成合格的API文档，于是乎我马上把Swagger换成了smart-doc，只能说真香，再也不用写@ApiModel这种注解了。