Swagger常用注解的使用

文
章
目
录

• Swagger常用的注解说明
• @ApiImplicitParam的参数说明：
• Swagger常用的注解使用
• 返回类型
•  请求类型入参
•  返回数据
•  无注解情况
• @ApiModel
• @ApiModelProperty
• @ApiOperation
• @ApiParam

前两节我们讲了《Springboot如何集成Swagger》，这一节我们主要以Swagger2版本为例，讲下Swagger常用注解的使用。

Swagger常用的注解说明

• @Api：用在类上，说明该类的作用。
• @ApiOperation：注解来给API增加方法说明。
• @ApiParam：定义在参数上
• @ApiResponses：用于表示一组响应
• @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
  l code：数字，例如400
  l message：信息，例如”请求参数没填好”
  l response：抛出异常的类
• @ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
  l @ApiModelProperty：描述一个model的属性
• @ApiImplicitParams: 用在方法上包含一组参数说明。
• @ApiImplicitParam：用来注解来给方法入参增加说明。

@ApiImplicitParam的参数说明：

参数名	含义	取值
paramType	指定参数放在哪个地方	header：请求参数放置于Request Header，使用@RequestHeader获取 query：请求参数放置于请求地址，使用@RequestParam获取 path：（用于restful接口）–>请求参数的获取：@PathVariable body：（不常用） form（不常用）
name	参数名
dataType	参数类型
required	参数是否必须传	true | false
value	说明参数的意思
defaultValue	参数的默认值

Swagger常用的注解使用

我们先准备一个接口类UserController

@RestController
@RequestMapping(\"/user\")
public class UserController {

    @PostMapping(value = \"/query-user-info\")
    public ResponseResult queryUserInfo(@RequestBody UserRequest userRequest) {
        // 省略查询逻辑
        return ResponseResult.success(new User(userRequest.getId(), \"小明\"));
    }
}

还有几个涉及到的实体类，分别作为入参、返回类型、返回数据。

返回类型

@Data
@AllArgsConstructor
@NoArgsConstructor
public class ResponseResult {
    private Integer code;
    private String message;
    private Object data;

    public static ResponseResult success(Object data) {
        return new ResponseResult(0, \"请求成功\", data);
    }
}

 请求类型入参

@Data
@AllArgsConstructor
@NoArgsConstructor
public class UserRequest {
    private Integer id;
}

 返回数据

@Data
@AllArgsConstructor
@NoArgsConstructor
public class User {
    private Integer id;
    private String name;
}

 无注解情况

此时，我们还没有添加任何swagger注解，Swagger 会将接口请求或者相应的实体类信息展示在 Models 下的，运行查看如下图，发现请求体和返回类型都都显示了出来：

由此可见，前端web页面可通过看 Models 知道后端定义实体类的信息。

@ApiModel

该注解是作用于类上面的，是用来描述类的一些基本信息的。

相关属性：

• value：提供类的一个备用名，如果不设置，默认情况下将使用 class 类的名称
• description：对于类，提供一个详细的描述信息
• parent：这个属性用于描述的是类的一些父类信息
• discriminator：这个属性解释起来比较麻烦，因为这个类主要体现在断言当中
• subTypes：可以通过这个属性，指定我们想要使用的子类

比如：这个为给 UserRequest 这个类添加该注解：

@Data
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = \"用户查询请求体\", description = \"用于接收查询请求数据\")
public class UserRequest {
    private Integer id;
}

效果如下：

可以看到这里的名字从 UserRequest 变成 用户查询请求体 了，并且多出了description描述信息。

@ApiModelProperty

它的作用是添加和操作属性模块的数据。这里我还是以UserRequest 类为例，为该类的属性添加说明：

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = \"用户查询请求体\", description = \"用于接收查询请求数据\")
public class UserRequest {
    @ApiModelProperty(\"用户id\")
    private Integer id;
}



可以看到这里对该字段类型下面有一个备注说明。

更多属性请参考《Swagger @ApiModelProperty详解》

@ApiOperation

该注解用来对某个方法/接口进行描述。这里我以 UserController 下的接口为例：

@PostMapping(value = \"/query-user-info\")
@ApiOperation(value = \"根据id查询用户详情\")
public ResponseResult queryUserInfo(@RequestBody UserRequest userRequest) {
    // 省略查询逻辑
    return ResponseResult.success(new User(userRequest.getId(), \"小明\"));
}



可以看到该接口就有了对其功能的描述信息。

更多属性请参考：《Swagger @ApiOperation 详解》

@ApiParam

该注解使用在方法上或者参数上，字段说明，表示对参数的添加元数据（说明或者是否必填等）

相关属性：

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

这里我以 UserController 下的接口为例：

@PostMapping(value = \"/query-user-infos\")
@ApiOperation(value = \"条件查询用户信息\")
public ResponseResult queryUserInfos(
        // name 用户名称 不必填
        @ApiParam(value = \"用户姓名\", required = false) @RequestParam(required = false) String name,
        // gender 用户性别 必填
        @ApiParam(value = \"用户性别\", required = true) @RequestParam(required = true) String gender
) {
    return ResponseResult.success(new User());
}



我们看到gender有必填标记，而name没有，两个属性后面也都有中中文说明其含义。