Swagger常用注解

一、什么是Swagger?

Swagger是一款Restful接口的文档在线自动生成和功能测试功能软件。
Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。说白了就是给前端小姐姐看文档用的。

二、注解

@Api:用于controller类上，说明该类的作用

tags=“说明该类的作用，可以在UI界面上看到的注解”
value=“该参数没什么意义，在UI界面上也看到，所以不需要配置”

@ApiOperation：用在controller的方法上，用来说明方法用途、作用

value=“说明方法的用途、作用”
notes=“方法的备注说明”

@ApiImplicitParam：用来给方法入参增加说明

name：参数名
value：参数的汉字说明、解释
dataType：参数类型，默认String
required ：参数是否必传，true必传
defaultValue：参数的默认值
paramType：参数放在哪个地方
header请求参数的获取:@RequestHeader,参数从请求头获取
query请求参数的获取:@RequestParam,参数从地址栏问号后面的参数获取
path（用于restful接口）请求参数的获取：@PathVariable，参数从URL地址上获取
body（不常用）参数从请求体中获取
form（不常用）参数从form表单中获取

@ApiImplicitParams：用在controller的方法上，一组@ApiImplicitParam
@ApiResponse：用在 @ApiResponses里边，一般用于表达一个错误的响应信息

code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类

@ApiResponses：用在controller的方法上，用于表示一组响应
@ApiModel：用在返回对象类上，描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在出入参数对象的字段上，表示对model属性的说明或者数据操作更改