四、注解说明

注意：注解中其实会有很多的属性，该文章只列出部分常用的属性而已，其他不常用属性请查看其他人博客！

@Api

@Api

@Api : 
    位置：用在请求的类上，例如Controller，
    作用：说明该类的主要作用。
    参数说明：@Api("tags":"", "value":"", "description ":"")
        tags：说明该类的作用，参数是个数组，可以填多个。
        value="该参数没什么意义，在UI界面上不显示，所以不用配置"
        description = "用户基本信息操作"

代码示例如下：

@RestController
@RequestMapping("/swagger")
@Api(tags = "用户管理")
@Slf4j
public class SwaggerController {}

网站效果展示：

@ApiOperation

@ApiOperation

@ApiOperation：
    位置：用在请求方法上
    作用：说明方法的用途、作用
    参数说明：@ApiOperation("value":"", "notes":"", "tags ":"")
        value="方法的用途和作用"
        notes="方法的注意事项和备注"			
        tags：说明该方法的作用， 参数是个数组，可以填多个。例如格式：tags={"作用1","作用2"}

代码示例如下：

@GetMapping("/getList")
@ApiOperation(value = "分页查询", notes = "分页查询的注意事项和备注", tags = {"说明该方法的作用1,说明该方法的作用2"})
public Response<PageResult<User>> getList(@RequestParam int pageNo, @RequestParam int pageSize){

网站效果展示：

@ApiImplicitParams

@ApiImplicitParams

@ApiImplicitParams: 
    位置：用在请求方法上
    作用：包含多@ApiImplicitParam，包含一组参数说明。
    参数说明：@ApiImplicitParams({@ApiImplicitParam("name":"", "value":"", "dataType":"", "paramType":"", "required":"")...})

代码示例如下：

@GetMapping("/getList")
@ApiOperation(value = "分页查询", notes = "分页查询的注意事项和备注", tags = {"说明该方法的作用1,说明该方法的作用2"})
@ApiImplicitParams({
    @ApiImplicitParam(name = "pageNo", value = "当前页码，从1开始", paramType = "query", required = true, dataType="int") ,
    @ApiImplicitParam(name = "pageSize", value = "每页显示记录数", paramType = "query",required = true, dataType="int") ,
    })
public Response<PageResult<User>> getList(@RequestParam int pageNo, @RequestParam int pageSize){

@ApiImplicitParam

@ApiImplicitParam

@ApiImplicitParam：
    位置：用在请求方法上
    作用：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面说明
    参数说明：@ApiImplicitParam("name":"", "value":"", "dataType":"", "paramType":"", "required":"")
        name="参数名称"
        value="参数说明"
        dataType="数据类型"，默认String
        required=true 参数是否必选
        paramType="query" 表示参数放在哪里，查询参数类型，这里有几种形式：
            header --> 请求参数的获取：@RequestHeader，参数在 request headers 里边提交
            query --> 请求参数的获取：@RequestParam，直接跟参数，完成自动映射赋值
            path（用于 restful 接口）--> 请求参数的获取：@PathVariable，以地址的形式提交数据
            body（不常用）--> 以流的形式提交 仅支持 POST
            form（不常用）--> 以 form 表单的形式提交 仅支持 POST

代码示例如下：

@GetMapping("/getList")
@ApiOperation(value = "分页查询", notes = "分页查询的注意事项和备注", tags = {"说明该方法的作用1,说明该方法的作用2"})
@ApiImplicitParams({
    @ApiImplicitParam(name = "pageNo", value = "当前页码，从1开始", paramType = "query", required = true, dataType="int") ,
    @ApiImplicitParam(name = "pageSize", value = "每页显示记录数", paramType = "query",required = true, dataType="int") ,
    })
public Response<PageResult<User>> getList(@RequestParam int pageNo, @RequestParam int pageSize){

网站效果展示：

@ApiResponses

@ApiResponses

@ApiResponses：用在请求的方法上，表示一组响应

代码示例如下：

@GetMapping("/getList")
@ApiResponses({
     @ApiResponse(code=400,message="请求参数及格式不对"),
      @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
    })
public Response<PageResult<User>> getList(@RequestParam int pageNo, @RequestParam int pageSize){

@ApiResponse

@ApiResponse

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
    code：数字，例如400
    message：信息，例如"请求参数没填好"
    response：抛出异常的类

代码示例如下：

@GetMapping("/getList")
@ApiResponses({
    @ApiResponse(code=400,message="请求参数及格式不对"),
    @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
})
public Response<PageResult<User>> getList(@RequestParam int pageNo, @RequestParam int pageSize){

网站效果展示：