Swagger常用注解详解

一、注解概述

常用注解：

@Api()用于类；

表示标识这个类是swagger的资源 ，@Api 注解用于标注一个Controller（Class）

@ApiOperation()用于方法；

表示一个http请求的操作

@ApiParam()用于方法，参数，字段说明；

表示对参数的添加元数据（说明或是否必填等）

@ApiModel()用于类

表示对类进行说明，用于参数用实体类接收

@ApiModelProperty()用于方法，字段

表示对model属性的说明或者数据操作更改

@ApiIgnore()用于类，方法，方法参数

表示这个方法或者类被忽略

@ApiImplicitParam() 用于方法

表示单独的请求参数

@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

二、注解使用

@Api

@Api 注解用于标注一个Controller==（Class）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。

@Api属性一览表：

示例代码：

@Controller
@Slf4j
@RequestMapping("/user")
@Api(tags = "人员信息 API", description = "提供人员信息相关的 Rest API",value="controller类")
public class UserController extends BaseController {
}

@[ApiOperation

@ApiOperation 注解在用于对一个操作或HTTP方法进行描述（用于@mapping方法上）==。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。

示例代码：

@ApiOperation("根据id查询")
@GetMapping("/getById/{id}")
public Stutest getById(@ApiParam(name = "id",required = true) 
                       @PathVariable("id") Long id){
    Stutest byId = stutestService.getById(id);
    return byId;
}

@ApiParam

@ApiParam作用于请求方法上，定义api参数的注解。

示例代码：

• name： 参数名
• value： 参数说明
• required：是否必填

public ResponseEntity<User> getUserById(
    @ApiParam(name="id",value = "ID of user that needs to be fetched",
              allowableValues = "range[1,10]", required = true)
    @PathVariable("UserId") Long userId)

@ApiImplicitParams、@ApiImplicitParam

@ApiImplicitParams、@ApiImplicitParam 都可以定义参数.

(1).@ApiImplicitParam() 用于方法

表示单独的请求参数

(2).@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam ，用在请求的方法上，包含一组参数说明；

• name–参数名字
• value–参数说明
• dataType–数据类型
• paramType–参数类型
• example–举例说明

代码示例：

@ApiImplicitParams({
    //参数效验
    @ApiImplicitParam(name="phonenum",value="手机号",required=true,paramType="form"),
    @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
    @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
@PostMapping("/login")
public ApiResult login(@RequestParam String mobile, @RequestParam String password,
                       @RequestParam Integer age){
    //...
    return JsonResult.ok(map);
}

@ApiResponses、@ApiResponse

@ApiResponses、@ApiResponse进行方法返回对象的说明。

代码示例：

@ApiResponses({
    @ApiResponse(code = 200, message = "请求成功"),
    @ApiResponse(code = 400, message = "请求参数没填好"),
    @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
}) 
@ResponseBody
@RequestMapping("/user")
public ApiResult getUser(@RequestParam String userId) {
    ...
}

@ApiModel、@ApiModelProperty

@ApiModel用于描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）。

@ApiModelProperty用来描述一个Model的属性

使用场景

• @ApiModel 用在模型类上,对模型类作注解
• @ApiModelProperty 用在属性上,对属性作注解

代码演示:

//人员信息表
@Data
@ApiModel(description= "返回人员信息")
public class UserQueryVo extends BaseEntity{

    @ApiModelProperty(value = "主键", required = true)
    @TableId(value = "id", type = IdType.ID_WORKER)
    private Long id;

    @ApiModelProperty(value = "手机号", required = true)
    private String phonenum;

    @ApiModelProperty(value = "密码", required = true)
    private String password;

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