@ApiModel注解与@ApiModelProperty注解

一、@ApiModel注解与@ApiModelProperty注解

资料来源： https://juejin.cn/post/7109835493952454693

1.1 初了解

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

@ApiModelProperty注解则是作用在接口相关实体类的属性（字段）上的注解，用来对具体的接口相关实体类中的参数添加额外的描述信息，除了可以和 @ApiModel 注解关联使用，也会单独拿出来用。

作用域不同，@ApiModel作用在类上，@ApiModel作用来属性上

1.2 Maven坐标

导入swagger的依赖：

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-annotations</artifactId>
    <version>1.5.13</version>
</dependency>

​

1.3 ApiModel

主要的属性有value属性和description属性

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

具体使用就如上面的例子一样，如果不使用value时，默认值就是实体类的名称，所以除非有特殊说明或者实体类不清晰，否则直接使用默认值即可。

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

比如上面的例子，如果想对用户实体添加必要的描述信息，可以如下所示：

java">@ApiModel(value="用户实体类，用户相关字段", description="用户实体中包含用户相关的所有业务字段，主要字段有姓名、年龄、性别，用于登录使用")
publicclassUser{
}

1.4 ApiModelProperty

属性：value、name、required 、hidden、allowEmptyValue

@Data
@ApiModel(value="用户实体类，用户相关字段", description="用户实体中包含用户相关的所有业务字段，主要字段有姓名、年龄、性别，用于登录使用")
publicclassUser {
​
    @ApiModelProperty("主键")
    privateIntegerid;
​
    @ApiModelProperty("姓名")
    privateStringname;
}

​

1.4.1 value属性

对实体类中的字段进行描述和补充说明，解释该字段代表什么意思。

理解为它就是一个注释的作用，方便清楚字段的含义。

@ApiModelProperty(
    value="是否成功：200-成功，其他失败",
    required=true,
    example="200"
)
private String code;

1.4.2 name属性

name属性即重写该属性名字，比如上述例子，name可以这样使用

@ApiModelProperty(value="user表主键Id",name="id")
   private Integer id;

1.4.3 required 属性

required属性就是用来描述实体中的参数字段是否必传,默认false，如果使用true，则该字段后面会有一个红色的星号

@ApiModelProperty(value="user表主键Id",name="id",required=true)
   private Integer id;
   
   @ApiModelProperty(required=false)//或者不行就是默认false
   private Integer age;
​

1.4.4 hidden属性

用来描述实体中参数字段是否显示在Swagger界面中，默认也是false，true表示隐藏。

   @ApiModelProperty(hidden=true)
   private String address;

1.4.5 allowEmptyValue属性

用来描述实体参数的值是否可以为空值。在 ApiModelProperty 注解中直接声明 allowEmptyValue属性的值即可，如果不声明该属性，则默认为false，即字段参数的值不可以为空。

使得master字段声明其值可以为空，即在参数传递时可以不填充值

  @ApiModelProperty(allowEmptyValue=true)
   private String master;

1.4.6 example属性

@ApiModelProperty(
    value="是否成功：200-成功，其他失败",
    required=true,
    example="200"
)
private String code;

1.4.7 dataType属性

表示的是字段的类型

@ApiModelProperty(required=false，dataType="int")//或者不写就是默认false
   private Integer age;