【Swagger2】Swagger2 常用注解

@[TOC]

以创建一个Controller，定义一个接口，讲述Swagger2的常用注解

@Api【定义Controller请求类】

@Slf4j
@RequestMapping("/user")
@RestController
@Api(tags = "用户信息管理", description = "详细描述")
public class UserController {
}

@Api 注解的主要作用是对Controller，也可以称之为对请求类做一个描述，它有几个常用参数，下面解释一下它们的用处

参数名	描述
tags	用于表示该请求类在文档中的标签名称
description	详细描述
position	设置该请求类在文档中的位置顺序
protocols	协议类型，如: http, https
hidden	该文档是否隐藏，默认为tree

效果图：

@ApiOperation【描述接口说明】

@Slf4j
@RequestMapping("/user")
@RestController
@Api(tags = "用户信息管理", description = "详细描述")
public class UserController {

    @Autowired
    private IUserService iUserService;

    @GetMapping("/userInformationByUserId")
    @ApiOperation(value = "获取用户信息", notes = "根据用户Id获取用户信息")
    public UserInformationVo userInformationById(String userId) {
        final UserInfoEntity userInfoEntity = iUserService.userInfoByUserId(userId);
        UserInformationVo userInformationVo = new UserInformationVo();
        BeanUtils.copyProperties(userInfoEntity, userInformationVo);
        return userInformationVo;
    }

}

@ApiOperation 注解的主要是对接口做出描述，它有几个常用参数，下面解释一下它们的用处

参数名	描述
value	描述接口的作用
notes	接口的备注

效果图：

@ApiImplicitParams【接口的一组入参参数】、@ApiImplicitParam【描述接口中单个参数说明】

@Slf4j
@RequestMapping("/user")
@RestController
@Api(tags = "用户信息管理", description = "详细描述")
public class UserController {

    @Autowired
    private IUserService iUserService;

    @GetMapping("/userInformationByUserId")
    @ApiImplicitParams({
    		@ApiImplicitParam(name = "userId", required = true, value = "用户Id", paramType = "header", dataType = "Integer", defaultValue = "0")
    })
    @ApiOperation(value = "获取用户信息", notes = "根据用户Id获取用户信息")
    public UserInformationVo userInformationById(String userId) {
        final UserInfoEntity userInfoEntity = iUserService.userInfoByUserId(userId);
        UserInformationVo userInformationVo = new UserInformationVo();
        BeanUtils.copyProperties(userInfoEntity, userInformationVo);
        return userInformationVo;
    }

}

@ApiImplicitParams 注解的作用就是描述接口中多个参数

@ApiImplicitParam 是描述单个参数说明，它有几个常用参数，下面解释一下它们的用处

参数名	描述
name	参数名
value	参数备注
required	该参数是否必穿
paramType	参数放在哪个地方【path（restful接口）、query、body、header、form】
dataType	参数数据类型
defaultValue	参数默认值

效果图：

@ApiResponses【一组响应状态码与描述】、@ApiResponse【响应状态码与描述】

@Slf4j
@RequestMapping("/user")
@RestController
@Api(tags = "用户信息管理", description = "详细描述")
public class UserController {

    @Autowired
    private IUserService iUserService;

    @GetMapping("/userInformationByUserId")
    @ApiImplicitParams({
    		@ApiImplicitParam(name = "userId", required = true, value = "用户Id", paramType = "header", dataType = "Integer", defaultValue = "0")
    })
    @ApiResponses({
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 9999, message = "未知错误")
    })
    @ApiOperation(value = "获取用户信息", notes = "根据用户Id获取用户信息")
    public UserInformationVo userInformationById(String userId) {
        final UserInfoEntity userInfoEntity = iUserService.userInfoByUserId(userId);
        UserInformationVo userInformationVo = new UserInformationVo();
        BeanUtils.copyProperties(userInfoEntity, userInformationVo);
        return userInformationVo;
    }

}

@ApiResponses 注解的作用就是描述接口多个响应状态

@ApiResponse 是单个响应状态码与描述，它有几个常用参数，下面解释一下它们的用处

参数名	描述
code	响应状态码
message	响应说明

效果图：

@ApiModel【描述入参对象与出参对象】、@ApiModelProperty【描述对象中单个参数】

@Slf4j
@RequestMapping("/user")
@RestController
@Api(tags = "用户信息管理", description = "详细描述")
public class UserController {

    @Autowired
    private IUserService iUserService;

    @GetMapping("/userInformationByUserId")
    @ApiImplicitParams({
    		@ApiImplicitParam(name = "userId", required = true, value = "用户Id", paramType = "header", dataType = "Integer", defaultValue = "0")
    })
    @ApiResponses({
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 9999, message = "未知错误")
    })
    @ApiOperation(value = "获取用户信息", notes = "根据用户Id获取用户信息")
    public UserInformationVo userInformationById(String userId) {
        final UserInfoEntity userInfoEntity = iUserService.userInfoByUserId(userId);
        UserInformationVo userInformationVo = new UserInformationVo();
        BeanUtils.copyProperties(userInfoEntity, userInformationVo);
        return userInformationVo;
    }

}

返回对象：

@Setter
@Getter
@ToString
@ApiModel(description = "用户信息")
public class UserInformationVo {

    @ApiModelProperty(value = "id", required = true, position = 1)
    private String id;

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

    @ApiModelProperty(value = "年龄", required = true, position = 3)
    private Integer age;

    @ApiModelProperty(value = "性别：0、女 1、男", required = true, position = 4)
    private Integer gender;

}

@ApiModel 注解的作用是描述入参与出参对象

@ApiModelProperty 是描述单个参数，它有几个常用参数，下面解释一下它们的用处

参数名	描述
value	参数名
required	参数是否必传
position	参数在文档中的位置

效果图：

End