一分钟完成springboot项目整合Swagger2实现自动生成接口文档

一份好的接口文档能够让接口调用者很清晰的知道如何调用一个API接口，包括请求方式、传参规范、接口返回信息等；也能帮助团队新人快速了解业务。

传统的做法是由开发人员维护一个API接口文档，一般是一个word文档或一个提供接口文档管理的网站。这种做法有很多弊端：文档难以维护、浪费开人员时间、文档难以与接口保持一致等。

Swagger2的出现很好的解决了上述问题，可以实现接口文档实时在线生成，提供在线接口测试功能。唯一的弊端就是对接口程序有侵入，但本人认为还是利大于弊的。

接下来我们将Swagger2整合到springboot项目中，并用swagger-bootstrap-ui对Swagger2进行界面美化，废话不多说，我们开始。。。

在pom.xml中导入

在application.yml中设置swagger2是否开启的开关，关闭后接口文档被关闭，在生产环境部署时就需要关闭接口文档。

1.创建注解SwaggerCustomIgnore.java，主要用于忽略某些不想生成接口文档的接口。

2.创建配置类SpringfoxSwagger2Config.java，配置Swagger接口文档生成规则和过滤规则。

3.拦截器排除swagger相关资源，新建或修改WebConfig.java文件，内容如下。

1.编写内容参考如下

2.注解说明

启动项目，浏览器输入http://location:8081/doc.html,效果如下。

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。 前端和后端的唯一联系，变成了API接口；API文档变成了前后端开发人员联系的纽带，变得越来越重要，swagger就是一款让你更好的书写API文档的框架，而且swagger可以完全模拟http请求，入参出参和实际情况差别几乎为零。

没有API文档工具之前，大家都是手写API文档的（维护起来相当困难），在什么地方书写的都有，有在confluence上写的，有在对应的项目目录下readme.md上写的，每个公司都有每个公司的玩法，无所谓好坏。但是能称之为“框架”的，估计也只有swagger了

除了通过包路径配置扫描接口外，还可以通过配置其他方式扫描接口，这里注释一下所有的配置方式：

1、配置接口扫描过滤

上述方式可以通过具体的类、方法等扫描接口，还可以配置如何通过请求路径配置：

这里的可选值还有：

2、配置要忽略的请求参数

可以通过ignoredParameterTypes()方法去配置要忽略的参数：

3、配置是否启动Swagger

通过enable()方法配置是否启用swagger，如果是false，swagger将不能在浏览器中访问了：

**4、如何动态配置当项目处于test、dev环境时显示swagger，处于prod时不显示？

**

5、配置API分组

如果没有配置分组，默认是default。通过groupName()方法即可配置分组：

如下图所示，我们配置了groupName("user")那么当前接口分组信息为user。

6、实体配置

比如当前项目中有这么一个实体：

只要这个实体在请求接口的返回值上（即使是泛型），都能映射到实体项中：

注：并不是因为@ApiModel这个注解让实体显示在这里了，而是只要出现在接口方法的返回值上的实体都会显示在这里，而@ApiModel和@ApiModelProperty这两个注解只是为实体添加注释的。

@ApiModel为类添加注释

@ApiModelProperty为类属性添加注释

为什么要引入Swagger?

有过后台开发和前端联调的人都会被接口文档折磨，更新不及时，文档和代码不一致，无法调试，swagger就是为了解决这个问题。

看下swagger官方介绍

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

如此好的利器，怎么在后台框架中快速集成呢？

第一步、添加maven依赖

需要在系统的pom中添加如下依赖：

第二步、添加swagger配置文件

第三步、测试

浏览器输入：http://localhost:8080/swagger-ui.html ，能测试生成的api是否可用。

总结

很好用的开源框架，集成也很简单，建议大家在工程中使用，能够快速开发，减少前后端沟通api的时间成本。

---