@ApiImplicitParamsController 注解详解

@ApiImplicitParams 注解用于在某个操作（方法或 HTTP 接口）上面添加参数说明信息。该注解下面可以声明多个 @ApiImplicitParam 子注解，其中每个 @ApiImplicitParam 注解用来描述一个参数信息。实例如下：

@ApiOperation(value = "验证 @ApiImplicitParams 注解",
        notes = "验证 @ApiImplicitParams 注解的用法")
@ApiImplicitParams({
        @ApiImplicitParam(name = "sex", value = "性别", required = false,
                dataType = "Long", paramType = "query", defaultValue = "0"),
        @ApiImplicitParam(name = "name", value = "名称", required = true,
                dataType = "String", paramType = "query")
})
@GetMapping("/demo1")
public List<User> demo1(@RequestParam(defaultValue = "1") Long sex, String name) {
    return new ArrayList<>();
}

效果图如下：

从上图得知，/apiImplicitParams/demo1 接口声明了两个参数，分别为 sex 和 name，其中 name 参数为必填参数。

springboot广告位

在 @ApiImplicitParams 注解中，定义了如下用来描述参数的属性：

• name：指定参数名，例如：name="sex"；

• value：指定参数的说明、解释信息。例如：value="性别"；

• required：指定参数是否必须传递，例如：@ApiImplicitParam(name = "name", value = "名称", required = true, dataType = "String", paramType = "query") 表示 name 参数为必传参数；

• paramType：指定参数放在哪个地方，可选值如下：

• header：表示请求参数通过 HTTP 请求头进行传递，请求参数可以通过 @RequestHeader 注解获取；

• query：表示请求参数为通常的参数，如：get 方法 url 传递的参数。可以通过 @RequestParam 注解进行获取；

• path：（用于 restful 接口）请求参数可以通过 @PathVariable 注解获取；

• body：不常用

• form：不常用    

• dataType：指定参数类型，默认String。例如：dataType = "Long"

• defaultValue：指定参数的默认值，例如：

@ApiImplicitParam(name = "sex", value = "性别", required = false,
        dataType = "Long", paramType = "query", defaultValue = "0")

更多实例

（1）验证声明 HTTP 请求头类型的参数，如下：

@ApiOperation(value = "验证 @ApiImplicitParams 注解",
        notes = "验证 @ApiImplicitParams 注解的用法")
@ApiImplicitParams({
        @ApiImplicitParam(name = "token", value = "TOKEN", required = true,
                dataType = "String", paramType = "header")
})
@GetMapping("/demo2")
public List<User> demo2() {
    return new ArrayList<>();
}

效果图：

（2）验证声明 Restful Path 类型的参数，如下：

@ApiOperation(value = "验证 @ApiImplicitParams 注解",
        notes = "验证 @ApiImplicitParams 注解的用法")
@ApiImplicitParams({
        @ApiImplicitParam(name = "sex", value = "性别", required = true,
                dataType = "String", paramType = "path"),
        @ApiImplicitParam(name = "name", value = "姓名", required = true,
                dataType = "String", paramType = "path")
})
@GetMapping("/demo3")
public List<User> demo3(Long sex, String name) {
    return new ArrayList<>();
}

效果图：