Swagger-Extension 和 ExtensionProperty 注解

1. 前言

本節會結合一個用戶登錄接口方法來為大家介紹 Swagger 中的兩個關聯注解 - Extension 和 ExtensionProperty 及所提供的常用屬性。

Extension 和 ExtensionProperty 不能單獨使用，需要搭配 @ApiOperation 注解使用，單獨使用沒有任何效果。

在實際項目中也是很少用到，其提供的屬性也是很少，所以我們只需要掌握他們最基本的用法和常用屬性即可。

重點講解的屬性：

• Extension 注解的 name 、 properties ；

• ExtensionProperty 注解的 name 、 value 。

2. 什么是 Extension 和 ExtensionProperty 注解 ？

Extension 和 ExtensionProperty 這兩個注解屬于關聯注解，都是用來對接口方法中之外的但是也是和這個方法有關的參數屬性進行描述說明，即都是針對接口方法之外但是也和這個方法有關的參數進行補充說明，在 Swagger 中這一類的參數我們稱為接口方法拓展參數 (如果對這個概念不理解，請自行查閱)。

下面我們來看一下 Extension 和 ExtensionProperty 兩個注解中都包括哪些常用屬性。

3. 注解主要屬性匯總

Extension 注解

ExtensionProperty 注解

4. 屬性詳解

4.1 Extension 注解相關屬性

name () 和 properties () 屬性

定義：

name 屬性就是定義拓展參數數組列表的名稱，也可以理解為定義拓展參數的名稱。

properties 屬性就是定義拓展參數的列表，即將拓展參數放到一個數組里面，可以是一個也可以是多個。

使用方法：

name 和 properties 兩個屬性雖然屬于 @Extension 注解，但是 @Extension 注解不能單獨拿來使用，需要和 @ApiOperation 注解一起搭配才能使用，因為在 @ApiOperation 注解中存在一個名為 extensions 的屬性，其屬性的值就是通過 @Extension 注解來描述的。

例如，對于用戶登錄方法，我想為其添加一個拓展參數，那我們可以這樣寫：@Extension(name = "用戶登錄拓展參數", properties = { @ExtensionProperty(name = "userEmail", value = "user email") } )（現在你不需要理解業務代碼代表什么意思，重點看所使用的注解及屬性即可，下同）。

@ApiOperation(value = "user", 
            extensions = { 
            @Extension(name = "用戶登錄拓展參數", properties = { 
                    @ExtensionProperty(name = "userEmail", value = "user email") } ) })
public ServerResponse<User> login(User user){
    // do something...
} 

代碼解釋：

1-3 行，我們在用戶登錄接口方法的上方通過使用 @ApiOperation 注解來使用 @Extension 注解的 name 和 properties 屬性，由于篇幅有限，這里就不給大家截圖演示了。

Tips ：

1. 在使用 @Extension 注解及其相關屬性時，一定要看清楚該注解是通過哪種方法進行使用的。
2. 在實際項目開發中，一般具體的一個接口很少會出現拓展參數，如果存在，那也是通過業務需求來描述的，我們不能隨意編造任何拓展參數。

4.2 ExtensionProperty 注解相關屬性

name () 和 value () 屬性

定義：

name 屬性是用來描述接口方法中每一個拓展參數的名稱，即給每一個拓展參數都起一個名字。

value 屬性表示每一個接口方法中的拓展參數的具體的值，或者對拓展參數的解釋說明。

使用方法：

name 和 value 兩個屬性的使用方法和 @Extension 注解中屬性的使用方法相同，這里還是以 @ApiOperation 注解為例，詳細代碼使用方法如下。

@ApiOperation(value = "user", 
            extensions = { 
            @Extension(name = "用戶登錄拓展參數", properties = { 
                    @ExtensionProperty(name = "userEmail", value = "user email") } ) })
public ServerResponse<User> login(User user){
    // do something...
} 

代碼解釋：

我們可以看到，ExtensionProperty 注解中，屬性的使用方法，是通過 @ApiOperation 注解中的 properties 屬性來定義的，這里不再贅述。

Tips ：

1. 在使用 ExtensionProperty 注解時，注意是和 @ApiOperaion 注解中的哪個屬性進行搭配，其固定的代碼方式是什么，這是同學們需要理清的地方。
2. ExtensionProperty 注解的兩個屬性經常用于指名多個接口方法中的拓展參數，很少會只指名一條，在實際開發中，如果接口方法存在多個拓展參數，那么應該都指名出來才對。

5. 小結

本小節對 Swagger 中的 Extension 和 ExtensionProperty 注解及其該注解中的常用屬性做了詳細介紹，針對兩個注解中經常在實際項目開發中使用的屬性進行了重點介紹和應用剖析。

在學習 Extension 和 ExtensionProperty 注解及其常用屬性時，各位同學需要注解和其他注解搭配的使用方法，因為這兩個注解均不能單獨拿出來使用。