Swwager 注解使用说明

2. @Api

2.2 属性value、tags二者的区别

value属性作用在类和作用在方法上都用于描述；

tags属性作用在类和作用在方法上都用于分组，但分组的效果区别很大：

tags作用在类上时，会对全局的方法分组，即根据tags属性值复制多份，此时方法上的tags值无效，方法上tags配或不配效果都一样。

tags作用在方法上时，会根据当前类的所有方法的tags值做分组，粒度更细。

2.3 使用方法

3. @ApiOperation

用在方法上，对请求方法进行描述。

3.1 注解的属性

3.2 使用方法

@ApiOperation(value = "test1接口",notes = "test1接口详细描述")
public ApiResult<String> test1(@RequestParam String aa, @RequestParam String bb, @RequestParam String cc) {
}

常用在方法上，对请求参数列表进行描述。 其中的value属性可包含多个@ApiImplicitParam，对每个参加进行具体的描述。

5. @ApiImplicitParams

用在方法上，对请求参数进行描述。当需要对多个参数进行描述时，作为@ApiImplicitParams的属性使用。

5.1 注解的属性

5.2 使用方法

6. @ApiParam

用在方法、参数、类的字段上，对请求参数进行描述。

6.1 注解的属性

6.2 使用方法

@GetMapping("test2")
public ApiResult<TestRes> test2(@ApiParam(value = "aa的说明") @RequestParam String aa, @ApiParam(value = "bb的说明") @RequestParam String bb) {
        return ApiUtil.success(new TestRes());
}

8 @ApiModelProperty

用在类上，对请求、响应类,实体类进行描述。

8.1 注解的属性

8.2 使用方法

注意：java和scala在@ApiModelProperty注解上的使用的区别

9. @ApiResponses

用在方法、类上，对响应状态码列表进行描述。

9.1 注解的属性

用在方法上，对响应状态码进行描述。一般作为@ApiResponses的属性使用。

10.1 注解的属性

@GetMapping("test2")
@ApiOperation(value = "test2接口",notes = "test2接口详细描述")
        @ApiResponse(code = 200, message = "请求成功", responseHeaders = {@ResponseHeader(name = "header1", description = "header1的描述",response = String.class)}),
        @ApiResponse(code = 401, message = "没有权限"),
        @ApiResponse(code = 403, message = "禁止访问")
})
public ApiResult<TestRes> test2(@ApiParam(value = "aa的说明") @RequestParam String aa, @ApiParam(value = "bb的说明") @RequestParam String bb) {
}