Swagger（5）：Swagger2常用注解

1 Api

@Api是类上注解。控制整个类生成接口信息的内容。

• tags：类的名称。可以有多个值，多个值表示多个副本。
• description:描述，已过时。

注解如下：

@Api(tags = {"MyController","Swagger学习控制器"}, description = "测试API类型描述信息")

效果如下：

上面设置了两个tags，MyController和Swagger学习控制器，所以下图显示两个

2 ApiOperation

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

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

    @ApiOperation(value="post方法，执行数据新增操作", notes = "Swagger学习使用-处理POST请求的方法")

效果示例：在swagger-ui中显示效果

3 ApiParam

@ApiParam写在方法参数前面。用于对参数进行描述或说明是否为必添项等说明。

• name：参数名称
• value：参数描述
• required：是否是必须

    @GetMapping("/get")
    public String get(
            @ApiParam(name = "用户名（a）", value = "新增用户时提供的用户名", required = true) String a,
            @ApiParam(name = "密码（b）", value = "新增用户提供的密码", required = true)String b){
        return "get";
    }

效果示例：在swagger-ui中显示效果

4 ApiIgnore

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

示例如下：

效果示例：

5 ApiImplicitParam

@ApiImplicitParam用在方法上，表示单独的请求参数，总体功能和@ApiParam类似。

• name：属性名
• value：描述
• required：是否是必须的
• paramType：属性类型
• dataType：数据类型

代码示例：

@ApiImplicitParam(name = "m", value = "m参数描述", required = false, paramType = "字符串", dataType = "名值对")

如果希望在方法上配置多个参数时，使用@ApiImplicitParams进行配置。示例如下：

    @ApiImplicitParams(value={
            @ApiImplicitParam(name = "m", value = "m参数描述", required = false, paramType = "字符串", dataType = "string"),
            @ApiImplicitParam(name = "n", value = "n参数描述", required = true, paramType = "字符串(String)", dataType = "string")
    })

swagger-ui.html效果展示

6 ApiModel

@ApiModel是类上注解，主要应用Model，也就是说这个注解一般都是写在实体类上。

• value：名称
• description：描述

代码示例：

/**
 * ApiModel - 描述一个实体类型。这个实体类型如果成为任何一个生成api帮助文档方法的
 * 返回值类型的时候，此注解被解析。
 */
@ApiModel(value = "自定义实体-MyEntity", description = "MyEntity存储用户数据")
public class MyEntity implements Serializable {

效果如下：

7 ApiModelProperty

@ApiModelProperty可以用在方法或属性上。用于当对象作为参数时定义这个字段的内容。

• value：描述
• name：重写属性名
• required：是否是必须的
• example：示例内容
• hidden：是否隐藏。

代码示例：

    @ApiModelProperty(value = "姓名", name = "姓名(name)",
            required = true, example = "张三", hidden = false
    )

​​​​​​​

效果如下;