Swagger 中 @ApiImplicitParam和@ApiImplicitParams的用途

迈不过友情╰ 2022-11-06 05:52 394阅读 0赞

1、@ApiImplicitParam

作用在方法上，用于设置单个请求参数，用法示例：

@PutMapping("/update")
    @ApiOperation(value = "更新用户信息", notes = "根据用户登录token更新客户端提交的用户资料")
    public Object update() {
        Map<String,Object> map = new HashMap<>();
        map.put("list", null);
        return map;
    }

2、@ApiImplicitParams  
作用在方法上，用于包含多个 @ApiImplicitParam，用法示例：

@PostMapping("/register")
    @ApiOperation(value = "用户注册", notes = "APP用户注册")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "mobile", value = "手机号码", dataType = "string", paramType = "query", example = "13802780104", required = true),
            @ApiImplicitParam(name = "user_name", value = "登录账号", dataType = "string", paramType = "query", example = "lihailin9073", required = true),
            @ApiImplicitParam(name = "password", value = "登录密码", dataType = "string", paramType = "query", example = "123456", required = true),
            @ApiImplicitParam(name = "validate_code", value = "注册验证码", dataType = "string", paramType = "query", example = "3679", required = true)
    })
    public Object create() {
        Map<String,Object> map = new HashMap<>();
        map.put("list", null);
        return map;
    }

各个参数说明：   
   1. name ：参数名。   
   2. value ： 参数的具体意义，作用。   
   3. required ： 参数是否必填。   
   4. dataType ：参数的数据类型。   
   **5. paramType ：查询参数类型，这里有几种形式：**

**        path 以地址的形式提交数据  
        query 直接跟参数完成自动映射赋值  
        body 以流的形式提交 仅支持POST  
        header 参数在request headers 里边提交  
        form 以form表单的形式提交 仅支持POST**

被这个paramType坑过一次，当发POST请求的时候，当时接受的整个参数，不论用body还是query，后台都会报Body Missing错误；这个参数和SpringMvc中的@RequestBody冲突，去掉paramType对接口测试并没有影响

Swagger 注解说明

*  @Api：用在类上，说明该类的作用。
 *  @ApiOperation：注解来给API增加方法说明。
 *  @ApiImplicitParams : 用在方法上包含一组参数说明。
 *  @ApiImplicitParam：用来注解来给方法入参增加说明。
 *  @ApiResponses：用于表示一组响应
 *  @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
 *  @ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
 *  @ApiModelProperty：描述一个model的属性