使用smart-doc自动生成接口文档，解放java开发者

方式	好处	缺点
word文档和confluence	有文档留存（好像也不算好处）	费时费力、多人编写不便
swagger	1、不用专门写文档 2、通过连接直接访问 3、在线测试，有点像简化的postman	注释太多，写的想打人
jApiDoc	1、引入jar包，一键生成html接口文档 2、侵入小，添加简单注释就行	1、功能单一，只能接口文档 2、作者好久没有维护了
smart-doc	1、引入maven插件，一键生成HTML接口文档 2、作者很活跃，社区也很活跃，反应问题很快就有新版本解决 3、能生成常用的html，markdown、postman接口文档 4、侵入小，添加简单注释就行 5、适配单服务、微服务等多种环境	1、需要抽两个小时看下官方文档

2、JApiDocs简介

前面我介绍过一种工具，叫做JApiDocs，这个工具我也使用了一段时间，用起来还是不错的，能满足基本要求，文档链接地址

3、前言

被写接口文档难受了好久,使用swagger要加各种稀奇古怪的注释，十分繁琐，突然看到JApiDocs 的介绍，只需要在接口上加上点注释，就能够生成接口文档。突然来了希望，通过看文档自己使用之后，把踩过的坑记录下来

生成的接口文档页面展示：

查询接口

新增接口

删除接口

官方说明文档：

文档内容，说明、使用范文很齐全，特别适合我们使用，我会举个例子，大家如果要使用的话，还是抽一两个小时看看官方文档，会有很大帮助，文档地址如下：

https://gitee.com/smart-doc-team/smart-doc/wikis/smart-doc%20maven%E6%8F%92%E4%BB%B6?sort_id=1791450

4、快速使用

添加插件

<plugin>
    <groupId>com.github.shalousun</groupId>
    <artifactId>smart-doc-maven-plugin</artifactId>
    <version>2.0.8</version>
    <configuration>
        <!--指定生成文档的使用的配置文件,配置文件放在自己的项目中-->
        <configFile>./src/main/resources/smart-doc.json</configFile>
        <!--指定项目名称-->
        <projectName>测试</projectName>
        <!--smart-doc实现自动分析依赖树加载第三方依赖的源码，如果一些框架依赖库加载不到导致报错，这时请使用excludes排除掉-->
        <excludes>
            <!--格式为：groupId:artifactId;参考如下-->
            <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>
                <!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
                <goal>html</goal>
            </goals>
        </execution>
    </executions>
</plugin>