Swagger-ApiModel 和 ApiModelProperty 注解詳解

1. 前言

本節(jié)會結(jié)合一個用戶操作相關(guān)的實體類，來給大家介紹 Swagger 中的兩個關(guān)聯(lián)注解 - ApiModel 注解和 ApiModelProperty 注解及所提供的常用屬性，使用率較低或基本不適用的注解屬性就不再介紹了。

ApiModel 注解和 ApiModelProperty 注解，在實際項目中的使用頻率較前面所介紹的注解而言相對較低，我們只需要了解它的作用和注意事項即可，不必重點掌握。

重點講解的屬性：

• ApiModel 注解的 value 、 description 屬性；

• ApiModelProperty 注解的 value 、required 、hidden 、 allowEmptyValue 屬性。

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

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

ApiModelProperty 注解是作用在接口相關(guān)實體類的參數(shù)上的注解，用來對具體的接口相關(guān)實體類中的參數(shù)添加額外的描述信息，常常和 @ApiModel 注解關(guān)聯(lián)使用，有時也會單獨拿出來用。

ApiModel 和 ApiModelProperty 兩個注解的作用域不同，但是都提供了豐富的屬性來允許我們對接口相關(guān)實體類和其中的參數(shù)添加額外的描述信息。

下面我們來看一下 ApiModel 和 ApiModelProperty 兩個注解中都包括哪些主要屬性。

3. 注解主要屬性匯總

ApiModel 注解

ApiModelProperty 注解

4. 屬性詳解

4.1 ApiModel 注解相關(guān)屬性

value() 屬性

定義：

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

使用方法：

在 ApiModel 注解中不使用 value 屬性時，則其默認值為實體類的名稱，如果我們想對一個實體類添加特定的描述信息，例如，對于用戶實體，我們可以這樣寫：value = "用戶實體，存儲用戶相關(guān)字段"（現(xiàn)在你不需要理解業(yè)務(wù)代碼代表什么意思，重點看實體類上使用的注解及屬性即可，下同）。

@ApiModel(value = "用戶實體，存儲用戶相關(guān)字段")
public class User{
    // do something...
}

代碼解釋：

第1行，我們在用戶實體類的上方定義了 ApiModel 注解的 value 屬性的值，來對用戶實體添加特定的描述信息。

顯示結(jié)果：

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

Tips ： 在實際開發(fā)工作中，value 屬性一般很少使用，只用默認的類型即可，如果有特別不直觀的類名，則會考慮使用該注解的 value 屬性。

description() 屬性

定義：

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

使用方法：

在 ApiModel 注解中直接聲明 description 屬性的值即可，例如，我想對用戶實體添加必要的描述信息，則可以這樣寫：description = "用戶實體中包含用戶相關(guān)的所有業(yè)務(wù)字段，如有需要請另行添加"。

@ApiModel(value = "用戶實體，存儲用戶相關(guān)字段", description = "用戶實體中包含用戶相關(guān)的所有業(yè)務(wù)字段，如有需要請另行添加")
public class User{
    // do something...
}

代碼解釋：

第1行，我們在用戶實體類的上方定義了 ApiModel 注解的 description 屬性的值來對用戶實體添加額外的描述信息。

顯示結(jié)果：

可以看到，在用紅框圈起來的地方就是我們使用 description 屬性來描述的信息了，值得注意的是，這里的顯示樣式是 Swagger 默認的，一般不需要修改。

Tips ：

1. 在實際開發(fā)工作中，description 屬性一般會配合 value 屬性進行使用，很少會出現(xiàn)只是用 value 屬性而不使用 description 屬性的情況。
2. description 屬性使用頻率同 value 屬性。

4.2 ApiModelProperty 注解相關(guān)屬性

value() 屬性

定義：

該屬性就是對實體類中的參數(shù)進行一個描述，即該屬性用來對實體類中的字段做一個補充說明，來說明該字段代表什么意思。

使用方法：

在 ApiModelProperty 注解中直接聲明 value 屬性的值即可，例如，在用戶實體類中有一個"Id"字段，我想對該字段添加描述信息，則可以這樣寫：value = "用戶Id"。(現(xiàn)在你不需要理解業(yè)務(wù)代碼代表什么意思，重點看使用的注解及屬性即可，下同）。

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

代碼解釋：

第1行，我們在 id 字段的上方定義了 ApiModelProperty 注解的 value 屬性的值來對 id 字段補充說明。

顯示結(jié)果：

可以看到，在用紅框圈起來的地方就是我們使用 value 屬性來描述的信息了。

Tips ： 在實際開發(fā)工作中，value 屬性相對而言還是很常用的，value 屬性的定義應(yīng)該言簡意賅，描述的時候不能太啰嗦。

required()、hidden() 屬性

定義：

required 屬性就是用來描述實體中的參數(shù)字段是否必傳。

hidden 屬性就是用來描述實體中參數(shù)字段是否顯示在 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 界面上顯示。

顯示結(jié)果：

可以看到，id 字段的后面有一個紅色的星號，這表明該字段必傳，這就是 required 屬性所起的作用。

在整個實體字段中并不能看到 phone 字段，這就是我們使用 hidden 屬性所起的作用，我們可以對比上述 value 屬性的結(jié)果圖來看。

Tips ：

1. 在實際開發(fā)工作中，hidden 屬性不能濫用，如果哪些字段需要隱藏，請向項目經(jīng)理提出申請。
2. required 屬性相對而言還是經(jīng)常使用的，required 屬性的定義應(yīng)當根據(jù)具體的業(yè)務(wù)需求，不要隨意定義，這會引起不必要的麻煩。

allowEmptyValue() 屬性

定義：

allowEmptyValue 屬性是用來描述實體參數(shù)的值是否可以為空。

使用方法：

在 ApiModelProperty 注解中直接聲明 allowEmptyValue 屬性的值即可，如果我們不聲明該屬性，則默認為 false，即字段參數(shù)的值不可以為空。

如果我們想對 phone 字段聲明其值可以為空，則可以這樣寫：allowEmptyValue = true。

   @ApiModelProperty(allowEmptyValue = true)
   private String phone;

代碼解釋：

第1行，我們在 phone 字段的上方定義了 ApiModelProperty 注解的 allowEmptyValue 屬性的值為 true ，代表該字段的值可以為空，在參數(shù)傳遞時可以不填充值。

顯示結(jié)果：

可以看到，在序號為 1 的標簽紅框中的 id 字段上，我們并沒有定義 allowEmptyValue 屬性，所以他默認將該屬性描述為了 false ， 即 id 參數(shù)的值在傳遞時不可以為空，必須為其填寫數(shù)據(jù)。

在序號為 2 標簽紅框中的 phone 字段上，我們定義了 allowEmptyValue 屬性的值為 true ，即 phone 參數(shù)的值在傳遞時可以為空，這就是 allowEmptyValue 屬性所起的作用。

Tips ： 在實際開發(fā)工作中，allowEmptyValue 屬性經(jīng)常和 required 屬性一起搭配使用，但是同樣不能濫用，如果哪些字段的值需要在傳遞時為空，請向項目經(jīng)理提出申請。

5. 小結(jié)

本小節(jié)對 Swagger 中的 ApiModel 和 ApiModelProperty 注解及其該注解做了詳細講解，針對兩個注解中，經(jīng)常在實際項目開發(fā)中使用的屬性，采用圖文并茂的方式，進行了重點介紹和應(yīng)用剖析，由于不同注解的很多屬性用法相同，這里就不再贅述了。

在學習 ApiModel 和 ApiModelProperty 注解及其常用屬性時，各位同學應(yīng)該在清楚，什么是實體類的基礎(chǔ)上進行學習，因為這兩個注解都是針對實體類而言的，其他地方無法使用。