一、@ApiModel注解與@ApiModelProperty注解

---

資料來源： https://juejin.cn/post/7109835493952454693

1.1 初了解

---

@ApiModel注解是用在接口相關(guān)的實體類上的注解，它主要是用來對使用該注解的接口相關(guān)的實體類添加額外的描述信息，常常和@ApiModelProperty注解配合使用

@ApiModelProperty注解則是作用在接口相關(guān)實體類的屬性（字段）上的注解，用來對具體的接口相關(guān)實體類中的參數(shù)添加額外的描述信息，除了可以和 @ApiModel 注解關(guān)聯(lián)使用，也會單獨拿出來用。

作用域不同，@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屬性就是對所需要特別說明的接口相關(guān)實體類進行描述。

具體使用就如上面的例子一樣，如果不使用value時，默認值就是實體類的名稱，所以除非有特殊說明或者實體類不清晰，否則直接使用默認值即可。

• description屬性就是對所需要特別說明的接口相關(guān)實體類進行較長的描述。

比如上面的例子，如果想對用戶實體添加必要的描述信息，可以如下所示：

@ApiModel(value="用戶實體類，用戶相關(guān)字段", description="用戶實體中包含用戶相關(guān)的所有業(yè)務(wù)字段，主要字段有姓名、年齡、性別，用于登錄使用")
publicclassUser{
}

1.4 ApiModelProperty

---

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

@Data
@ApiModel(value="用戶實體類，用戶相關(guān)字段", description="用戶實體中包含用戶相關(guān)的所有業(yè)務(wù)字段，主要字段有姓名、年齡、性別，用于登錄使用")
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屬性就是用來描述實體中的參數(shù)字段是否必傳,默認false，如果使用true，則該字段后面會有一個紅色的星號

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

1.4.4 hidden屬性

用來描述實體中參數(shù)字段是否顯示在Swagger界面中，默認也是false，true表示隱藏。

   @ApiModelProperty(hidden=true)
   private String address;

1.4.5 allowEmptyValue屬性

用來描述實體參數(shù)的值是否可以為空值。在 ApiModelProperty 注解中直接聲明 allowEmptyValue屬性的值即可，如果不聲明該屬性，則默認為false，即字段參數(shù)的值不可以為空。

使得master字段聲明其值可以為空，即在參數(shù)傳遞時可以不填充值

  @ApiModelProperty(allowEmptyValue=true)
   private String master;

1.4.6 example屬性

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

1.4.7 dataType屬性

表示的是字段的類型文章來源地址http://www.zghlxwxcb.cn/news/detail-439310.html

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