一、Swagger3使用及好处
1. 在如今前后端分离的时代，swagger能非常好的让前后端同学各司其职，根据API文档开发，提升效率
2. Swagger3能非常明晰的显示API接口说明，包括方法类型、输入输出，以及参数类型，返回值等，且针对参数及实体有非常详细的注释说明，让大家对接口本身功能及调用更加明晰
3. Swagger3本身也可以通过try it ot来快速调试问题，十分方便
Swagger是一个用于自动生成在线接口文档的框架，并可在线测试接口，可以很好的跟Spring结合，只需要添加少量的代码和注解即可，而且在接口变动的同时，即可同步修改接口文档，不用再手动维护接口文档
二、为Springboot添加Swagger3
1. 初始化生成Springboot结构，该部分不再详细描述，可以看之前介绍 [https://www.jianshu.com/p/7664e77bab2d](https://www.jianshu.com/p/7664e77bab2d)
2. 添加maven依赖
image.png
3. 添加swagger3配置
image.png
4. 添加测试实体(用户实体)
image.png
- 这里有一点，传统JAVA大家可能会去写get / set, 后面大家慢慢使用IDE推荐的自动生成Getter/Setter, 但使用Springboot后大家可以使用lombok插件，对于属性使用非常文件，只需要在类里加入@Data注解即可。那么如何安装lombok插件呢，大家可以在File->Settings->Plugins里搜索lombok, 搜索到安装即可，当然有可能出现在MarketPlace中无法找到该插件，此时可能是因为网络无法访问marketplace，大家可以在后面的设置里添加代理地址http://plugins.jetbrains.com，然后搜索，当然最好是重启下idea
image.png
- 完成后在pom.xml中添加lombok依赖
image.png
- 这里还有一点需注意，为了让实体的属性及实体本身注释也显示出来，这里需要加上ApiModel的注解，针对UserEntity类加入@ApiModel(value = "UserEntity", description = "用户信息实体")，针对其下属性加下@ApiModelProperty注解
5. Swagger使用，在restcontroller中针对类及方法加相关注解
- 在接口类上添加@Api(tags = "操作接口")，tags的值是该类的作用，在文档页面会显示，value不会显示
- 在需要生成文档的接口上添加注解@ApiOperation
- 对请求参数添加@ApiParam
image.png
三、最终显示结果情况
右键Run SpringbootswaggerApplication，启动完成后，在浏览器中输入[http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html)，显示如下
image.png
- 打开用户控制器，默认显示用户控制器下3个API方法
image.png
- 打开添加用户信息后如下：
image.png
如：添加一个姓名：test, 性别：男, 年龄: 29，点击Excute后正常返回true,用户添加成功
- 打开“获取用户信息列表”（无参），Excute后显示如下 ：
image.png
- 打开“通过用户名获取用户信息”，显示如下：
image.png
try it out后，在用户姓名里输入"jimmy"，结果如下：
image.png
文章参考文献地址：
- SpringBoot整合Swagger3生成接口文档https://zhuanlan.zhihu.com/p/161947638
- SPRINGBOOT配置SWAGGER接口文档参数及返回值注释详细操作：[https://www.freesion.com/article/3595581092/]
