Swagger前言
作者最近因为项目原因去学了Swagger，个人感觉Swagger极大便利了前后端交互。
我们都知道做前后端分离的项目时，接口文档是十分重要的，但是因为项目周期各种原因导致后端人员经常无法及时更新接口文档，导致前端开发人员十分的痛苦，经常出现接口文档与实际接口不符的情况。（这里我想替后端人员说一句，我们也很讨厌接口文档不规范，更新不及时，当时写这玩意儿是真的很痛苦啊！）
那么有没有一种东西能够让接口文档动态生成啊？哎~还真有，本文主角Swagger就可以完美解决这个问题
Open API
Open API规范(OpenAPI Specification)以前叫做Swagger规范，是REST API的API描述格式。
Open API文件允许描述整个API 包括：
- 每个访问地址的类型。（POST或GET）
- 每个操作的参数。（输入输出参数）
- 认证方法
- 连接信息，声明，使用团队和其他信息
Open API规范可以使用YAML或JSON格式进行编写。这样更利于我们和机器进行阅读。
OpenAPI规范(OAS)为REST API定义了一个与语言无关的标准接口，允许人和计算机发现和理解服务的功能，而无需访问源代码，文档或通过网络流量检查。正确定义后，消费者可以使用最少量的实现逻辑来理解远程服务并与之交互。
然后，文档生成工具可以使用OpenAPI定义来显示API，使用各种编程语言生成服务器和客户端的代码生成工具，测试工具以及许多其他用例。
Swagger简介
Swagger是一套围绕Open API规范构建的开源工具，可以帮助设计，构建，记录和使用REST API。
Swagger工具包括的组件：
-
Swagger Editor：基于浏览器编辑器，可以在里面编写Open API规范。类似Markdown具有实时预览描述文件的功能
-
Swagger UI：将Open API规范呈现为交互式API文档。用可视化UI展现描述文件。
-
Swagger Codegen：将Open API规范生成为服务器存根和客户端库。通过Swagger Codegen可以将描述文件生成html格式和cwiki形式的接口文档，同时也可以生成多种语言的可无端和客户端代码。
-
Swagger Inspector：和Swagger UI有点类似，但是可以返回更多信息，也会保存请求的实际参数数据。
-
Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和付费版。
使用Swagger，就是吧相关的信息存储在它定义的描述文件里面(yml或json格式),再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。
Springfox
使用Swagger时如果碰见版本更新或迭代时，只需要更改Swagger的描述文件即可。但是频繁的更改项目版本时很多开发人员认为即使修改描述文件（yml或json）也是一定的工作负担，久而久之就直接修改代码，而不去修改描述文件了，这样基于描述文件生成的接口文档也就失去了意义 
Swagger极致用法（入门案例）
1.首先我们先编写一个SpringBoot项目：
导入依赖：
2. 编写Controller类用于测试Swagger：
3.添加Swagger相关依赖：
4.开启Swagger注解：
5.访问SwaggerUI界面： 默认地址为：localhost:项目端口号/swagger-ui.html
ok，我们发现SwaggerUI界面确实出现了我们controller中的访问方法。
需要注意的是：
至于Swagger-ui我就不详细说明用法了，大家可以自己探索，下面给几个举例用法：
Swagger配置
基础配置
然后我们还可以指定Swagger扫描那个controller包：
自定义注解实现不生成帮助文档：
首先我们先创建一个自定义注解： 
然后我们再到Swagger配置类中进行配置，具体怎么配置呢？请看下面的代码：
这里有个需要注意的地方，这里的代码和我上面的代码不太一样，为什么？
因为我上面用的是Swagger3.0，Swagger3.0版本对Predicates.not()方法进行了剔除，而是以下面的方式代替：
路径范围配置
如果想选择性的使用多个路径可以这样写：
又又又需要注意的是：
Swagger常用注解
@Api
我们重启项目打开Swagger-ui界面看一下：
对比图：
@ApiOperation
这个注解是用来对某一个请求方法进行描述的。 
@ApiIgnore
这个注解描述的方法或者类型，不生成api帮助文档，与我们之前自定义的注解效果等同：
@ApiParam
这个注解是用来描述请求方法的参数的： 
@ApiImplicitParams
这个注解和@ApiParam效果等同，但是这个方法是加在方法上的：
单个参数： 
多个参数：
@ApiModel和@ApiModeProperty
这两个注解都是标注自定义的实体类来使用的：
注意 在Swagger3.0中，对于方法参数描述的注解，推荐使用更简洁的@Parameter()注解，@ApiParam和@ApiImplicitParams这两个注解有些过时了。
总结
Swagger极大的便捷了接口文档的编写，使得后端开发人员可以更专注于业务逻辑和代码编写，而不用花过多时间来编写接口文档，文档的更新迭代，开发信息都能及时更新，不需要后端开发人员实时手动编写更新接口文档，Swagger自动帮我们完成了。
以上就是对Swagger的介绍了，希望可以帮到大家，如果对您有帮助，敬请给个点赞给作者，谢谢了！！
