Swwager 注解使用说明

1. swwager注解的作用域

2. @Api

使用位置即用在类上，对请求类进行描述。标识一个Controller类是Swagger文档类。

2.1 注解的属性

2.2 属性value、tags二者的区别

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

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

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

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

2.3 使用方法

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

*java
@Api(tags = "Swagger测试相关接口")
@RestController
*scala
@Api(tags = Array("Swagger测试相关接口"))
@RestController

3. @ApiOperation

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

3.1 注解的属性

3.2 使用方法

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

4. @ApiImplicitParams

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

4.1 注解的属性

5. @ApiImplicitParams

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

5.1 注解的属性

5.2 使用方法

@GetMapping("test1")
@ApiOperation(value = "test1接口",notes = "test1接口详细描述")
@ApiImplicitParams(value = {
        @ApiImplicitParam(name = "aa",value = "aa的说明",defaultValue = "1",allowableValues = "1,2,3",required = true),
        @ApiImplicitParam(name = "bb",value = "bb的说明",defaultValue = "1",allowableValues = "1,2,3",required = true),
        @ApiImplicitParam(name = "cc",value = "cc的说明",defaultValue = "2",allowableValues = "1,2,3",required = true),
})

6. @ApiParam

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

6.1 注解的属性

6.2 使用方法

@GetMapping("test2")
@ApiOperation(value = "test2接口",notes = "test2接口详细描述")
public ApiResult<TestRes> test2(@ApiParam(value = "aa的说明") @RequestParam String aa, @ApiParam(value = "bb的说明") @RequestParam String bb) {
        return ApiUtil.success(new TestRes());
}

7. @ApiModel

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

7.1 注解的属性

8 @ApiModelProperty

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

8.1 注解的属性

8.2 使用方法

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

*java实体类
@Data
@ApiModel(description = "测试请求类")
public class TestReq {
    @ApiModelProperty(value = "用户ID",required = true)
    private Long userId;
    @ApiModelProperty(value = "用户名",example = "张三")
}
*scala实体类
@Data
@ApiModel(description = "测试响应类")
public class TestRes {
    @(ApiModelProperty @field)("用户ID")
    private Long userId;
    @(ApiModelProperty @field)("用户名")
}

9. @ApiResponses

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

9.1 注解的属性

10. @ApiResponse

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

10.1 注解的属性

10.2 使用方法

@GetMapping("test2")
@ApiOperation(value = "test2接口",notes = "test2接口详细描述")
@ApiResponses(value = {
        @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) {
        return ApiUtil.success(new TestRes());
}