@ApiModel注解与@ApiModelProperty注解

痛定思痛。 2024-03-25 09:56 85阅读 0赞

## **一、@ApiModel注解与@ApiModelProperty注解** ##

--------------------

> 资料来源： [https://juejin.cn/post/7109835493952454693][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**属性就是对所需要特别说明的接口相关实体类进行较长的描述。

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

@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;