Swagger 常用注解使用详解

在controller层使用@RequestParam的时候，发现这个参数是必须要输入值的，但是我们有时候必须查询的时候允许参数为空，使用这个注解就不行了。

在集成了swagger2后，找了半天的原因，发现使用@ApiImplicitParam这个注解可以解决这个问题。

常用注解

- @Api()用于类； 
表示标识这个类是swagger的资源 
- @ApiOperation()用于方法； 
表示一个http请求的操作 
- @ApiParam()用于方法，参数，字段说明； 
表示对参数的添加元数据（说明或是否必填等） 
- @ApiModel()用于类 
表示对类进行说明，用于参数用实体类接收 
- @ApiModelProperty()用于方法，字段 
表示对model属性的说明或者数据操作更改 
- @ApiIgnore()用于类，方法，方法参数 
表示这个方法或者类被忽略 
- @ApiImplicitParam() 用于方法 
表示单独的请求参数 
- @ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

具体使用举例说明：

1. @Api 用于类，说明该类的作用。可以标记一个Controller类做为swagger 文档资源

tags–表示说明 
value–也是说明，可以使用tags替代 
但是tags如果有多个值，会生成多个list

@Api(value="用户controller",tags={"用户操作接口"})
@RestController
public class UserController {
}

2. @ApiOperation() 用于方法；表示一个http请求的操作 
value用于方法描述 
notes用于提示内容 
tags可以重新分组（视情况而用） 
3.@ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等） 
name–参数名 
value–参数说明 
required–是否必填

4.@ApiModel()用于类 ；表示对类进行说明，用于参数用实体类接收 
value–表示对象名 
description–描述 
都可省略 
5.@ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改 
value–字段说明 
name–重写属性名字 
dataType–重写属性类型 
required–是否必填 
example–举例说明 
hidden–隐藏

8.

6.@ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上 
比较简单, 这里不做举例

7.@ApiImplicitParam() 用于方法 
表示单独的请求参数 
8.@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam 
name–参数ming 
value–参数说明 
dataType–数据类型 
paramType–参数类型 
example–举例说明

 paramType：表示参数放在哪个地方
    header-->请求参数的获取：@RequestHeader(代码中接收注解)
    query-->请求参数的获取：@RequestParam(代码中接收注解)
    path（用于restful接口）-->请求参数的获取：@PathVariable(代码中接收注解)
    body-->请求参数的获取：@RequestBody(代码中接收注解)
    form（不常用）