四Swagger2常用注解

Posted 2021-05-20 上善若水

一、swagger2常用注解

1.1、Api

@Api是类上注解。控制整个类生成接口信息的内容。
tags：类的名称。可以有多个值，多个值表示多个副本。
description：描述，已过时。

@RestController
@RequestMapping(value = "/person")
@Api(tags = {"PersonController","人员控制器"},description = "测试API类型描述信息")
public class PersonController {

在swagger-ui.html中显示效果

1.2、ApiOperation

@ApiOperation 写在方法上，对方法进行总体描述。

• value：接口描述
• notes：提示信息

    @PostMapping("/postReq")
    @ApiOperation(value = "接口描述",notes = "接口提示信息")
    public String postReq()
    {
        return "postReq";
    }

在swagger-ui.html中显示效果

1.3、ApiParam

@ApiParam 写在方法参数前面。用于对参数进行描述或说明是否为必填项等说明。
name：参数名称
value：参数描述
required：是否是必须

    @PostMapping("/postReq")
    @ApiOperation(value = "接口描述",notes = "接口提示信息")
    public String postReq(
            @ApiParam(name = "姓名",value = "新增用户时提供的姓名",required = true) String name,
            @ApiParam(name = "地址",value = "新增用户时提供的地址",required = false)String address)
    {
        return "postReq";
    }

在swagger-ui.html中显示效果

1.4、ApiModel

@ApiModel 是类上注解，主要应用于实体类Model，也就是说整个注解一般都是写在实体类上。
value：名称
description：描述

1.5、ApiModelProperty

@ApiModelProperty 可以用在方法或属性上。用于当对象作为参数时定义这个字段的内容。
value：描述
name：重写属性名
required：是否是必须的
example：示例内容
hidden：是否隐藏

@ApiModel(value = "自定义实体-Person",description = "Person存储人员数据")
public class Person implements Serializable {

    @ApiModelProperty(value = "人员id",name = "人员id(id)",required = false,example = "1",hidden = false)
    private Integer id;
    @ApiModelProperty(value = "人员姓名",name = "人员姓名(name)",required = true,example = "张三",hidden = false)
    private String name;
    @ApiModelProperty(value = "人员性别",name = "人员性别(gender)",required = false,example = "男",hidden = false)
    private String gender;
    private Integer age;
    private String address;

在swagger-ui.html中显示效果

1.6、ApiIgnore

@ApiIgnore用于方法或类或参数上，表示整个方法或类被忽略。和之前讲解的自定义注解@NotIncludeSwagger效果类似。只是这个注解是Swagger内置的注解，而@NotIncludeSwagger是我们自定义的注解。

1.7、ApiImplicitParam

@ApiImplicitParam用在方法上，表示单独的请求参数，总体功能和@ApiParam类似。
name：属性名
value：描述
required：是否是必须的
paramType：属性类型
dataType：数据类型

    @GetMapping("/getReq")
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "param1",value = "参数1",required = true),
            @ApiImplicitParam(name = "param2",value = "参数2",required = true)
    })
    public String getReq(String param1,String param2)
    {
        return "getReq";
    }

在swagger-ui.html中显示效果