持续创作，加速成长！这是我参与「掘金日新计划 · 6 月更文挑战」的第18天，点击查看活动详情
作者平台：
| CSDN：blog.csdn.net/qq_4115394…
| 知乎：www.zhihu.com/people/1024…
| GitHub：github.com/JiangXia-10…
| 微信公众号：1024笔记
本文一共2058字，预计阅读7分钟
1、前言
最近新的项目使用到了Swagger进行接口测试，在实体类上使用到了两个注解，一个是ApiModel注解，还有一个是ApiModelProperty注解，今天就一起学习下这两个注解的用处、属性以及具体的使用。
2、什么是 ApiModel 注解和 ApiModelProperty 注解
首先来说说，ApiModel 注解和 ApiModelProperty 注解到底是干嘛用的。毕竟它们两个还是很像的。
首先@ApiModel注解是用在接口相关的实体类上的注解，它主要是用来对使用该注解的接口相关的实体类添加额外的描述信息，并且常常和@ApiModelProperty注解配合使用。
而@ApiModelProperty注解则是作用在接口相关实体类的属性（字段）上的注解，用来对具体的接口相关实体类中的参数添加额外的描述信息，除了可以和 @ApiModel 注解关联使用，也会单独拿出来用。
所以可以理解为ApiModel和 ApiModelProperty两个注解的作用域不同，它们都是作用在接口相关的实体类上用来进行额外信息的描述，只是一个是作用在类上，一个作用在属性上。毕竟Property的中文意思就是属性。
使用它们需要导入swagger的依赖：
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.13</version>
</dependency>
3、ApiModel
首先看下它的具体使用和源码：
@ApiModel(value = "用户实体类，用户相关字段")
public class User{
}
源码如下：
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface ApiModel {
String value() default "";
String description() default "";
Class<?> parent() default Void.class;
String discriminator() default "";
Class<?>[] subTypes() default {};
String reference() default "";
}
所以可以发现其主要的属性有value属性和description属性。
value属性就是对所需要特别说明的接口相关实体类进行描述。具体使用就如上面的例子一样，如果不适用value时，默认值就是实体类的名称，所以除非有特殊说明或者实体类不清晰，否则直接使用默认值即可。
description属性就是对所需要特别说明的接口相关实体类进行较长的描述。比如上面的例子，如果想对用户实体添加必要的描述信息，可以如下所示：
@ApiModel(value = "用户实体类，用户相关字段", description = "用户实体中包含用户相关的所有业务字段，主要字段有姓名、年龄、性别，用于登录使用")
public class User{
}
4、ApiModelProperty
还是先看具体使用和源码：
@Data
@ApiModel(value = "用户实体类，用户相关字段", description = "用户实体中包含用户相关的所有业务字段，主要字段有姓名、年龄、性别，用于登录使用")
public class User {
@ApiModelProperty("主键")
private Integer id;
@ApiModelProperty("姓名")
private String name;
}
源码：
@Target({ElementType.METHOD, ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiModelProperty {
String value() default "";
String name() default "";
String allowableValues() default "";
String access() default "";
String notes() default "";
String dataType() default "";
boolean required() default false;
int position() default 0;
boolean hidden() default false;
String example() default "";
boolean readOnly() default false;
String reference() default "";
}
可以发现ApiModelProperty注解的属性较多，这里就不进行一一演示，其中使用较多的属性有：value、name、required 、hidden以及allowEmptyValue属性。
value属性就是对实体类中的字段进行描述和补充说明，解释该字段代表什么意思。比如，如果上述的实体类中的id字段信息，可以对其进行描述，比如：
@ApiModelProperty(value = "user表主键Id")
private Integer id;
所以可以理解为它就是一个注释的作用，方便清楚字段的含义。
name属性即重写该属性名字，比如上述例子，name可以这样使用：
@ApiModelProperty(value = "user表主键Id",name="id")
private Integer id;
required属性就是用来描述实体中的参数字段是否必传,默认false，如果使用true，则该字段后面会有一个红色的星号，比如：
@ApiModelProperty(value = "user表主键Id",name="id",required=true)
private Integer id;
@ApiModelProperty(required = false)//或者不行就是默认false
private Integer age;
hidden属性就是用来描述实体中参数字段是否显示在Swagger界面中，默认也是false，true表示隐藏。比如：
@ApiModelProperty(value = "user表主键Id",name="id",required=true)
private Integer id;
@ApiModelProperty(required = false)//或者不写就是默认false
private Integer age;
@ApiModelProperty(hidden = true)
private String address;
allowEmptyValue属性是用来描述实体参数的值是否可以为空值。在 ApiModelProperty 注解中直接声明 allowEmptyValue属性的值即可，如果不声明该属性，则默认为false，即字段参数的值不可以为空。
比如如果想使得master字段声明其值可以为空，即在参数传递时可以不填充值：
@ApiModelProperty(value = "user表主键Id",name="id",required=true)
private Integer id;
@ApiModelProperty(required = false)//或者不写就是默认false
private Integer age;
@ApiModelProperty(hidden = true)
private String address;
@ApiModelProperty(allowEmptyValue = true)
private String master;
example属性表示对该字段进行举例，比如name字段，值可以是张三：
@ApiModelProperty(value = "user表主键Id",name="id",required=true)
private Integer id;
@ApiModelProperty(required = false)//或者不写就是默认false
private Integer age;
@ApiModelProperty(hidden = true)
private String address;
@ApiModelProperty(allowEmptyValue = true)
private String master;
@ApiModelProperty(example = "张三")
private String master;
dataType属性表示的是字段的类型，比如age字段是int类型：
@ApiModelProperty(value = "user表主键Id",name="id",required=true)
private Integer id;
@ApiModelProperty(required = false，dataType = "int")//或者不写就是默认false
private Integer age;
@ApiModelProperty(hidden = true)
private String address;
@ApiModelProperty(allowEmptyValue = true)
private String master;
@ApiModelProperty(example = "张三")
private String master;
5、总结
本文主要介绍了Swagger中的常用到的ApiModel注解和ApiModelProperty注解，并对这两个注解的使用和常用的属性进行了解释和演示。可以理解为ApiModel和 ApiModelProperty两个注解的作用域不同，它们都是作用在接口相关的实体类上用来进行额外信息的描述，只是一个是作用在类上，一个作用在属性上。毕竟Property的中文意思就是属性。
