SpringBoot之整合Swagger2

Posted 2023-03-09

参考技术A

随着互联网技术的发展，现在的网站架构基本都由原来的后端渲染，变成了：前端渲染、先后端分离的形态，而且前端技术和后端技术在各自的道路上越走越远。 前端和后端的唯一联系，变成了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为类属性添加注释