Swagger-ApiModel 和 ApiModelProperty 注解詳解

1. 前言

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

ApiModel 注解和 ApiModelProperty 注解，在實(shí)際項(xiàng)目中的使用頻率較前面所介紹的注解而言相對(duì)較低，我們只需要了解它的作用和注意事項(xiàng)即可，不必重點(diǎn)掌握。

重點(diǎn)講解的屬性：

• ApiModel 注解的 value 、 description 屬性；

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

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

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

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

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

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

3. 注解主要屬性匯總

ApiModel 注解

ApiModelProperty 注解

4. 屬性詳解

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

value() 屬性

定義：

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

使用方法：

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

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

代碼解釋：

第1行，我們?cè)谟脩魧?shí)體類的上方定義了 ApiModel 注解的 value 屬性的值，來對(duì)用戶實(shí)體添加特定的描述信息。

顯示結(jié)果：

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

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

description() 屬性

定義：

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

使用方法：

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

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

代碼解釋：

第1行，我們?cè)谟脩魧?shí)體類的上方定義了 ApiModel 注解的 description 屬性的值來對(duì)用戶實(shí)體添加額外的描述信息。

顯示結(jié)果：

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

Tips ：

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

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

value() 屬性

定義：

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

使用方法：

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

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

代碼解釋：

第1行，我們?cè)?id 字段的上方定義了 ApiModelProperty 注解的 value 屬性的值來對(duì) id 字段補(bǔ)充說明。

顯示結(jié)果：

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

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

required()、hidden() 屬性

定義：

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

hidden 屬性就是用來描述實(shí)體中參數(shù)字段是否顯示在 Swagger 界面中。

使用方法：

在 ApiModelProperty 注解中直接聲明 required 屬性的值即可，例如，在用戶實(shí)體類中有一個(gè)"Id"字段，我想聲明該字段是必傳的，則可以這樣寫：required = true, dataType = "Integer"。

對(duì)于 hidden 屬性而言，比如我想將用戶的手機(jī)號(hào)字段不顯示，那可以這樣寫hidden = true。

   @ApiModelProperty(value = "用戶Id", required = true)
   private Integer id;
   @ApiModelProperty(hidden = true)
   private String phone;

代碼解釋：

第1行，我們?cè)?id 字段的上方定義了 ApiModelProperty 注解的 required 屬性的值為 true ，代表該字段必傳。

第3行，我們?cè)?phone 字段的上方定義了 ApiModelProperty 注解的 hidden 屬性為 true ， 代表該字段不在 Swagger 界面上顯示。

顯示結(jié)果：

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

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

Tips ：

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

allowEmptyValue() 屬性

定義：

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

使用方法：

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

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

   @ApiModelProperty(allowEmptyValue = true)
   private String phone;

代碼解釋：

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

顯示結(jié)果：

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

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

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

5. 小結(jié)

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

在學(xué)習(xí) ApiModel 和 ApiModelProperty 注解及其常用屬性時(shí)，各位同學(xué)應(yīng)該在清楚，什么是實(shí)體類的基礎(chǔ)上進(jìn)行學(xué)習(xí)，因?yàn)檫@兩個(gè)注解都是針對(duì)實(shí)體類而言的，其他地方無法使用。