1、Swagger是什么
是一款让你更好的书写API文档的规范且完整的框架
提供描述、生产、消费和可视化RESTful Web Service
是由庞大的工具集合支撑的形式化规范，这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面
2、常用注解
（1） @Api 用在类上，说明该类的作用，可以标记一个controller类作为swagger文档资源，使用方式：
@Api(value = "/user", description = "Operations about user")
常用参数：
tags："说明该类的作用，非空时将覆盖value的值"
value："描述类的作用"
description：对api资源的描述，在1.5版本后不再支持
basePath：基本路径可以不配置，在1.5版本后不再支持
position：如果配置多个Api 想改变显示的顺序位置，在1.5版本后不再支持
produces：设置MIME类型列表（output），例："application/json, application/xml"，默认为空
consumes：设置MIME类型列表（input），例："application/json, application/xml"，默认为空
protocols：设置特定协议，例：http， https， ws， wss。
authorizations：获取授权列表（安全声明），如果未设置，则返回一个空的授权值。
hidden：默认为false， 配置为true 将在文档中隐藏复制代码
（2） @ApiOperation 用在方法上，说明方法的作用，每一个url资源的定义，使用方式：
@ApiOperation(value = "Find purchase order by ID",
notes = "For valid response try integer IDs with value <= 5 or > 10. Other values will generated exceptions",
response = Order,tags = {"Pet Store"})
常用参数：
value："说明方法的用途、作用"
notes："方法的备注说明"
tags：操作标签，非空时将覆盖value的值
response：响应类型（即返回对象）
responseContainer：声明包装的响应容器（返回对象类型）。有效值为 "List", "Set" or "Map"。
responseReference：指定对响应类型的引用。将覆盖任何指定的response（）类
httpMethod：指定HTTP方法，"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
position：如果配置多个Api 想改变显示的顺序位置，在1.5版本后不再支持
nickname：第三方工具唯一标识，默认为空
produces：设置MIME类型列表（output），例："application/json, application/xml"，默认为空
consumes：设置MIME类型列表（input），例："application/json, application/xml"，默认为空
protocols：设置特定协议，例：http， https， ws， wss。
authorizations：获取授权列表（安全声明），如果未设置，则返回一个空的授权值。
hidden：默认为false， 配置为true 将在文档中隐藏
responseHeaders：响应头列表
code：响应的HTTP状态代码。默认 200
extensions：扩展属性列表数组
（3） @ApiParam 请求属性，使用方式：
public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true) User user)
常用参数：
name：参数名称，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致
value：参数的简要说明。
defaultValue：参数默认值
required:属性是否必填，默认为false [路径参数必须填]
其他参数：
allowableValues:限制参数的可接受值。1.以逗号分隔的列表 2、范围值 3、设置最小值/最大值
access:允许从API文档中过滤参数。
allowMultiple:指定参数是否可以通过具有多个事件接受多个值，默认为false
hidden:隐藏参数列表中的参数。
example:单个示例
examples:参数示例。仅适用于BodyParameters
（4） @ApiResponse 响应配置，用在 @ApiResponses 中，一般用于表达一个错误的响应信,使用方式：
@ApiResponse(code = 400, message = "Invalid user supplied")
（5） @ApiResponses 响应集配置，用在请求的方法上，表示一组响应,使用方式：
@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
常用参数：
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
（6） @ResponseHeader 响应头设置，使用方式：
@ResponseHeader(name="head1",description="response head conf")
（7） @ApiIgnore 用于类或方法上，可以不被swagger显示在页面上
（8） @ApiModel 用在请求的类上，表示对类的说明；用于响应类上，表示返回一个响应数据的信息（这种一般用在post创建的时候，使用 @RequestBody这样的场景，请求参数无法使用 @ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性
使用方式：
@ApiModel(value="用户登录信息", description="用于判断用户是否存在")
public class UserModel implements Serializable{
private static final long serialVersionUID = 1L;
/**用户名 */
@ApiModelProperty(value="用户名")
private String account;
/**密码 */
@ApiModelProperty(value="密码")
private String password;
}
常用参数：
value:此属性的简要说明
name:允许覆盖属性名称
其他参数:
allowableValues:限制参数的可接受值。1.以逗号分隔的列表 2、范围值 3、设置最小值/最大值
access:允许从API文档中过滤属性。
notes:目前尚未使用。
dataType:参数的数据类型。可以是类名或者参数名，会覆盖类的属性名称。
required:参数是否必传，默认为false
position:允许在类中对属性进行排序。默认为0
hidden:允许在Swagger模型定义中隐藏该属性。
example:属性的示例。
readOnly:将属性设定为只读。
reference:指定对相应类型定义的引用，覆盖指定的任何参数值
（9） @ApiImplicitParams 用在请求的方法上，表示一组参数说明
@ApiImplicitParam:用在 @ApiImplicitParams注解中，指定一个请求参数的各个方面
使用方式：
@ResponseBody
@PostMapping(value="/login")
@ApiOperation(value = "登录检测", notes="根据用户名、密码判断该用户是否存在")
@ApiImplicitParams({
@ApiImplicitParam(name = "name", value = "用户名", required = false, paramType = "query", dataType = "String"),
@ApiImplicitParam(name = "pass", value = "密码", required = false, paramType = "query", dataType = "String")
})
public UserModel login(@RequestParam(value = "name", required = false) String account,
@RequestParam(value = "pass", required = false) String password){}
常用参数：
name：参数名，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致
value：参数的汉字说明、解释
required：参数是否必须传，默认为false [路径参数必填]
paramType：参数放在哪个地方
·header --> 请求参数的获取：@RequestHeader
·query --> 请求参数的获取：@RequestParam
·path（用于restful接口）--> 请求参数的获取：@PathVariable
·body（不常用）
·form（不常用）
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
其他参数：
allowableValues：限制参数的可接受值。1.以逗号分隔的列表 2、范围值 3、设置最小值/最大值
access：允许从API文档中过滤参数。
allowMultiple：指定参数是否可以通过具有多个事件接受多个值，默认为false
example：单个示例
examples：参数示例。仅适用于BodyParameters
3、Swagger的优势
a:支持API自动生成同步的在线文档：使用swagger后可以直接通过代码生成文档，不再需要自己手动编写接口文档，对程序员来说非常方便，可以节约写文档的时间去学习新的技术
b:提供web页面的在线测试API：光有文档还不够，Swagger生成的文档，还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口
4、Swagger的目标
swagger的目标是对REST API定义一个标准的且和语言无关的接口，可以让人和计算机拥有无需访问源码、文档或网络流量监测就可以发现和理解服务的能力，当通过swagger进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与底层接口所实现的接口类似，Swagger消除了调用服务时可能会有的猜测。
