Spring Boot Swagger2自动生成接口文档

一、简介

　　在当下这个前后端分离的技术趋势下，前端工程师过度依赖后端工程师的接口和数据，给开发带来了两大问题：

　　1、问题一、后端接口查看难：要怎么调用？参数怎么传递？有几个参数？参数都代表什么含义？

　　2、问题二、返回数据操作难：数据返回不对或者不够怎么办？怎么才能灵活的操作数据？

　　这是很多公司前后端分离之后带来的困扰，那怎么来解决这些问题？

　　问题一的一般解决方案：后端团队共同维护一个在线文档，每次改接口再去改对应的文档，但难免会遗漏，花的大力气但却效果平平。

　　问题二的一般解决方案：自己搭建一个Mock服务器，然后一个接口一个接口手动去录规则，还是一个费力的体力活。

　　那有没有最优的解决方案，来解决以上两个问题呢？答案是肯定的，那就是将要登场的“Swagger”和“Easy Mock”。

　　1.1 Swagger介绍

　　　　Swagger是全球最流行的接口文档自动生成和测试的框架，几乎支持所有的开发语言。

　　　　Swagger官网地址：https://swagger.io/

二、Swagger集成

　　2.1 添加依赖。

　　配置pom.xml，添加如下代码：

　　其中：

　　　　springfox-swagger2 用于JSON API文档的生成；

springfox-swagger-ui 用于文档界面展示。

　　2.2 注册Swagger

　　在源码的根目录也就是Appliction.java的同级目录，创建Java类“SwaggerConfig.java”（命名无所谓），代码如下

　　

　　其中“@ConditionalOnExpression”为Spring的注解，用户是否实例化本类，

　　用于是否启用Swagger的判断（生产环境需要屏蔽Swagger）

　　2.3 生产环境禁用Swagger

　　是否启用Swagger是在application.properties文件里配置的，配置如下：

　　swagger.enable=true

　　生产环境禁用，设置为false即可。

　　2.4 添加文档注释

　　完成以上三个步骤，已经完成了Spring Boot对Swagger的集成，但是文档不够友好，比如类、接口的中文说明、参数的说明，是没有的，需要在代码中完成

　　如下代码：

　　

　　写完代码运行项目，在浏览器输入：http://localhost:8080/swagger-ui.html 查看添加注释的效果，如下图：

　　

　　其中@Api是用来描述类的，@ApiOperation是用来描述方法的，@ApiImplicitParam是用来描述参数的，更多注解说明请看下文。

　三、Swagger文档注解

　　常用注解介绍

　　

　　我们现在已经对Swagger有了初步的认识，本节重点来看Swagger注解的使用。

　　Swagger注解的作用是给接口添加注释的。

　　3.1 @Api 类注释

　　　　@Api：用来描述类的，属性如下

　　　　1、tags 描述类的用途

　　　　2、value 对显示而言没有任何用途可以不用设置

　　代码示例：

　　@Api(tags = "文章接口")

　　3.2 @ApiOperation 方法注释

　　@ApiOperation：用来描述方法的，属性如下：

　　1、value 方法的描述

　　2、notes 方法备注说明

　　代码示例：

　　@ApiOperation(value = "获取所有文章", notes = "查询分页数据")

　　效果如下图：

　　

　　3.3 @ApiImplicitParams 参数注释

　　　　@ApiImplicitParams：描述多参数

　　　　@ApiImplicitParam：描述单参数

　　　　

　　代码示例：

　　

　　效果如下图：

　　

　　3.4 @ApiModel 实体对象描述

　　@ApiModel：实体类名描述，属性如下：

　　　　description 类描述

　　　　@ApiModelProperty：字段描述，属性如下：

　　　　　　value 字段描述

　　示例如下

　　

　　四、总结

　　到此为止所有内容已经演示完了，我们解决前后端分离带来接口管理难、数据操作难的问题。自动生成接口文档、一键模拟数据，让我们不再依赖后端，只专注前端的业务，等后端把接口写完之后，再进行联合调试就可以了，这样我们就不费吹灰之力搞定了所有难题，并且灵活的配置让我们可以不影响和污染生产环境，生产环境设置禁用Swagger即可，并且有了预览功能之后我们甚至连Postman都省了。