005-用到的注解

一、请求类的描述

注解	说明
@Api	对请求类的说明

案例：

@Api(tags = "测试日期格式化")
@Slf4j
@RequestMapping("/test7Controller")
@RestController
public class Test7Controller {

二、方法和方法参数的描述

注解	说明
@ApiOperation	方法的说明
@ApiImplicitParams	方法参数的说明
@ApiImplicitParam	用于指定单个参数的说明
@ApiParam	用于指定单个参数的说明

属性说明：

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
	@ApiImplicitParam：对单个参数的说明	    
	    name：参数名
	    value：参数的说明、描述
	    required：参数是否必须必填
	    paramType：参数放在哪个地方
	        · query --> 请求参数的获取：@RequestParam
	        · header --> 请求参数的获取：@RequestHeader	      
	        · path（用于restful接口）--> 请求参数的获取：@PathVariable
	        · body（请求体）-->  @RequestBody User user
	        · form（普通表单提交）	   
	    dataType：参数类型，默认String，其它值dataType="Integer"	   
	    defaultValue：参数的默认值

案例：

@ApiOperation(value = "查询车辆竞拍记录列表")
@ApiImplicitParams({
        @ApiImplicitParam(name = "vehicleId", value = "车辆ID", required = true, dataType = "Integer", paramType = "query"),
        @ApiImplicitParam(name = "page", value = "当前页", required = true, dataType = "Integer", paramType = "query"),
        @ApiImplicitParam(name = "rows", value = "每页条数", required = true, dataType = "Integer", paramType = "query"),
})
@GetMapping("/test")
public String test2(@ApiParam(name = "城市Id") @RequestParam(value = "businessNo", required = false) String businessNo,
                    @ApiParam(value = "尾款最晚支付时间", required = false, name = "balanceTimeStr") String balanceTimeStr) {
    return "success";
}

三、方法的响应状态的描述

注解	说明
@ApiResponses	方法返回值的说明
@ApiResponse	用于指定单个参数的说明

属性说明：

@ApiResponses：响应状态的说明。是个数组，可包含多个 @ApiResponse
	@ApiResponse：每个参数的说明
	    code：数字，例如400
	    message：信息，例如"请求参数没填好"
	    response：抛出异常的类

案例：

@ApiOperation(value = "查询车辆竞拍记录列表")
@ApiImplicitParams({
        @ApiImplicitParam(name = "vehicleId", value = "车辆ID", required = true, dataType = "Integer", paramType = "query"),
        @ApiImplicitParam(name = "page", value = "当前页", required = true, dataType = "Integer", paramType = "query"),
        @ApiImplicitParam(name = "rows", value = "每页条数", required = true, dataType = "Integer", paramType = "query"),
})
@ApiResponses({
        @ApiResponse(code = 200, message = "成功"),
        @ApiResponse(code = 500, message = "失败"),
})
@GetMapping("/test")
public JsonResult test2(@ApiParam(name = "城市Id") @RequestParam(value = "businessNo", required = false) String businessNo,
                        @ApiParam(value = "尾款最晚支付时间", required = false, name = "balanceTimeStr") String balanceTimeStr) {
    return JsonResult.success();
}

public class JsonResult {

    private Integer code;

    private String message;

    private Object data;

    public JsonResult(Integer code, String message, Object data) {
        this.code = code;
        this.message = message;
        this.data = data;
    }

    public static JsonResult success() {
        return new JsonResult(200, "success", null);
    }

    public static JsonResult success(Object data) {
        return new JsonResult(200, "success", data);
    }

    public static JsonResult error(String message) {
        return new JsonResult(500, message, null);
    }

}

四、对象的描述

注解	说明
@ApiModel	用在JavaBean类上，说明JavaBean的 整体用途
@ApiModelProperty	用在JavaBean类的属性上面，说明此属性的的含议

案例：

@Data
@ApiModel(description = "日期实体")
public class TestDateTimeFormat {

    @ApiModelProperty(value = "姓名", required = true)
    private String name;

    @ApiModelProperty(value = "地址", required = true)
    private String address;

    @ApiModelProperty(value = "电话号码")
    private String phoneNumber;

    @ApiModelProperty(value = "生日")
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date birthday;

}

五、忽略接口方法

注解	说明
@ApiIgnore	忽略接口方法

案例：
添加这个注解，在doc文档列表就看不到这个方法的接口文档

@ApiIgnore
@PostMapping("/test2")
public void test2(@RequestBody TestDateTimeFormat testDateTimeFormat){
    log.info("实体类：{}",testDateTimeFormat);
    // 实体类：TestJsonFormat(name=小明, address=北京市, phoneNumber=123456789, birthday=Thu Oct 10 14:42:20 CST 2024)
}