跳到主要内容

Swagger-ApiModel 和 ApiModelProperty 注解详解

1. 前言​

本节会结合一个用户操作相关的实体类，来给大家介绍 Swagger 中的两个关联注解 - ApiModel 注解和 ApiModelProperty 注解及所提供的常用属性，使用率较低或基本不适用的注解属性就不再介绍了。

ApiModel 注解和 ApiModelProperty 注解，在实际项目中的使用频率较前面所介绍的注解而言相对较低，我们只需要了解它的作用和注意事项即可，不必重点掌握。

重点讲解的属性：

  • ApiModel 注解的 value 、 description 属性；
  • ApiModelProperty 注解的 value 、required 、hidden 、 allowEmptyValue 属性。

2. 什么是 ApiModel 注解和 ApiModelProperty 注解 ？​

ApiModel 注解是作用在接口相关实体类上的注解，用来对该接口相关实体类添加额外的描述信息，常常和 @ApiModelProperty 注解配合使用。

ApiModelProperty 注解是作用在接口相关实体类的参数上的注解，用来对具体的接口相关实体类中的参数添加额外的描述信息，常常和 @ApiModel 注解关联使用，有时也会单独拿出来用。

ApiModel 和 ApiModelProperty 两个注解的作用域不同，但是都提供了丰富的属性来允许我们对接口相关实体类和其中的参数添加额外的描述信息。

下面我们来看一下 ApiModel 和 ApiModelProperty 两个注解中都包括哪些主要属性。

3. 注解主要属性汇总​

ApiModel 注解

属性名称属性类型默认值作用
value()String空自定义类的名称
description()String空为类添加长文本描述信息

ApiModelProperty 注解

属性名称属性类型默认值作用
value()String空定义参数描述信息
name()String空定义参数名称
required()booleanfalse定义参数是否必传
hidden()booleanfalse定义参数是否隐藏
allowEmptyValue()booleanfalse定义参数是否允许为空

4. 属性详解​

4.1 ApiModel 注解相关属性​

value() 属性​

定义：

该属性就是对所需要特别说明的接口相关实体类进行描述。

使用方法：

在 ApiModel 注解中不使用 value 属性时，则其默认值为实体类的名称，如果我们想对一个实体类添加特定的描述信息，例如，对于用户实体，我们可以这样写：value = "用户实体，存储用户相关字段"（现在你不需要理解业务代码代表什么意思，重点看实体类上使用的注解及属性即可，下同）。

@ApiModel(value = "用户实体，存储用户相关字段")
public class User{
    // do something...
}

代码解释：

第1行，我们在用户实体类的上方定义了 ApiModel 注解的 value 属性的值，来对用户实体添加特定的描述信息。

显示结果：

可以看到，在之前显示 User 的位置，显示了我们使用 ApiModel 注解的 value 属性所描述的信息了。

Tips ： 在实际开发工作中，value 属性一般很少使用，只用默认的类型即可，如果有特别不直观的类名，则会考虑使用该注解的 value 属性。

description() 属性​

定义：

description 属性就是对所需要特别说明的接口相关实体类进行较长的描述。

使用方法：

在 ApiModel 注解中直接声明 description 属性的值即可，例如，我想对用户实体添加必要的描述信息，则可以这样写：description = "用户实体中包含用户相关的所有业务字段，如有需要请另行添加"。

@ApiModel(value = "用户实体，存储用户相关字段", description = "用户实体中包含用户相关的所有业务字段，如有需要请另行添加")
public class User{
    // do something...
}

代码解释：

第1行，我们在用户实体类的上方定义了 ApiModel 注解的 description 属性的值来对用户实体添加额外的描述信息。

显示结果：

可以看到，在用红框圈起来的地方就是我们使用 description 属性来描述的信息了，值得注意的是，这里的显示样式是 Swagger 默认的，一般不需要修改。

Tips ：

  1. 在实际开发工作中，description 属性一般会配合 value 属性进行使用，很少会出现只是用 value 属性而不使用 description 属性的情况。
  2. description 属性使用频率同 value 属性。

4.2 ApiModelProperty 注解相关属性​

value() 属性​

定义：

该属性就是对实体类中的参数进行一个描述，即该属性用来对实体类中的字段做一个补充说明，来说明该字段代表什么意思。

使用方法：

在 ApiModelProperty 注解中直接声明 value 属性的值即可，例如，在用户实体类中有一个"Id"字段，我想对该字段添加描述信息，则可以这样写：value = "用户Id"。(现在你不需要理解业务代码代表什么意思，重点看使用的注解及属性即可，下同）。

   @ApiModelProperty(value = "用户Id")
   private Integer id;

代码解释：

第1行，我们在 id 字段的上方定义了 ApiModelProperty 注解的 value 属性的值来对 id 字段补充说明。

显示结果：

可以看到，在用红框圈起来的地方就是我们使用 value 属性来描述的信息了。

Tips ： 在实际开发工作中，value 属性相对而言还是很常用的，value 属性的定义应该言简意赅，描述的时候不能太啰嗦。

required()、hidden() 属性​

定义：

required 属性就是用来描述实体中的参数字段是否必传。

hidden 属性就是用来描述实体中参数字段是否显示在 Swagger 界面中。

使用方法：

在 ApiModelProperty 注解中直接声明 required 属性的值即可，例如，在用户实体类中有一个"Id"字段，我想声明该字段是必传的，则可以这样写：required = true, dataType = "Integer"。

对于 hidden 属性而言，比如我想将用户的手机号字段不显示，那可以这样写hidden = true。

   @ApiModelProperty(value = "用户Id", required = true)
   private Integer id;
   @ApiModelProperty(hidden = true)
   private String phone;

代码解释：

第1行，我们在 id 字段的上方定义了 ApiModelProperty 注解的 required 属性的值为 true ，代表该字段必传。

第3行，我们在 phone 字段的上方定义了 ApiModelProperty 注解的 hidden 属性为 true ， 代表该字段不在 Swagger 界面上显示。

显示结果：

可以看到，id 字段的后面有一个红色的星号，这表明该字段必传，这就是 required 属性所起的作用。

在整个实体字段中并不能看到 phone 字段，这就是我们使用 hidden 属性所起的作用，我们可以对比上述 value 属性的结果图来看。

Tips ：

  1. 在实际开发工作中，hidden 属性不能滥用，如果哪些字段需要隐藏，请向项目经理提出申请。
  2. required 属性相对而言还是经常使用的，required 属性的定义应当根据具体的业务需求，不要随意定义，这会引起不必要的麻烦。

allowEmptyValue() 属性​

定义：

allowEmptyValue 属性是用来描述实体参数的值是否可以为空。

使用方法：

在 ApiModelProperty 注解中直接声明 allowEmptyValue 属性的值即可，如果我们不声明该属性，则默认为 false，即字段参数的值不可以为空。

如果我们想对 phone 字段声明其值可以为空，则可以这样写：allowEmptyValue = true。

   @ApiModelProperty(allowEmptyValue = true)
   private String phone;

代码解释：

第1行，我们在 phone 字段的上方定义了 ApiModelProperty 注解的 allowEmptyValue 属性的值为 true ，代表该字段的值可以为空，在参数传递时可以不填充值。

显示结果：

可以看到，在序号为 1 的标签红框中的 id 字段上，我们并没有定义 allowEmptyValue 属性，所以他默认将该属性描述为了 false ， 即 id 参数的值在传递时不可以为空，必须为其填写数据。

在序号为 2 标签红框中的 phone 字段上，我们定义了 allowEmptyValue 属性的值为 true ，即 phone 参数的值在传递时可以为空，这就是 allowEmptyValue 属性所起的作用。

Tips ： 在实际开发工作中，allowEmptyValue 属性经常和 required 属性一起搭配使用，但是同样不能滥用，如果哪些字段的值需要在传递时为空，请向项目经理提出申请。

5. 小结​

本小节对 Swagger 中的 ApiModel 和 ApiModelProperty 注解及其该注解做了详细讲解，针对两个注解中，经常在实际项目开发中使用的属性，采用图文并茂的方式，进行了重点介绍和应用剖析，由于不同注解的很多属性用法相同，这里就不再赘述了。

在学习 ApiModel 和 ApiModelProperty 注解及其常用属性时，各位同学应该在清楚，什么是实体类的基础上进行学习，因为这两个注解都是针对实体类而言的，其他地方无法使用。