springboot集成swagger2导出api文档

前言：日常开发中经常会碰到写接口给别人调用，写也就罢了，还要一个完整描述的api接口使用说明，我们有没有什么好的工具在写完代码就可以出来一份api接口文档，并且还可以测试该接口可用性呢？答案当然有，接下来就介绍今天的主角：swagger2

以下使用环境：Intellij IDEA + swagger2 2.8.0版本 + maven项目
1、首先pom文件中引入依赖包：

io.springfox
springfox-swagger-ui
2.8.0


io.springfox
springfox-spi
2.8.0


io.swagger
swagger-annotations
1.5.22


io.springfox
springfox-schema
2.8.0


io.github.swagger2markup
swagger2markup
1.3.1


ch.netzwerg
paleo-core
0.10.2


nl.jworks.markdown_to_asciidoc
markdown_to_asciidoc
1.0

2、在我们的方法上进行一些api说明，具体如何使用swagger2的一些注解说明，大家可以参考这个文章说明（https://blog.csdn.net/weixin_41846320/article/details/82970204），这里截图我的一个方法的说明如下：

3、接下来我们就要开始导出文档操作了
3.1、首先我们要创建一个生成一个AsciiDocs格式文档，测试内容方法如下：

3.2、执行该测试方法成功后，在你项目刚设置的路径下会看到一个后缀是.adoc的文件，到这里我们已经成功了一半了
3.3、因为我们要生成的是.html格式的，所以我们还要在pom文件中安装一个插件：

sourceDirectory：就是我们测试方法中那个要生成的路径
outputDirectory：是我们要生成的html文件所存放路径

3.4、在idea中的 Run/Debug Configurations 中，新建一个Maven Build,名字任意, Working directory为当前工程路径，
Command line 填写 asciidoctor:process-asciidoc 命令，截图如下：

3.5、执行此Maven Build,执行成功后,会在outputDirectory路径下出现后缀是.html的文件，这就是我们要生成的html形式的API了，截图如 下：

好了，到这里，就算一个api接口完了，把这个静态html文档给前端测试等人员，一目了然，即使以后出现变化，咱们重新执行下测试方法，就出来新的一个api文档，是不是很方便。