Swagger-Extension 和 ExtensionProperty 注解

1. 前言

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

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

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

重點講解的屬性：

• Extension 注解的 name 、 properties ；

• ExtensionProperty 注解的 name 、 value 。

2. 什么是 Extension 和 ExtensionProperty 注解 ？

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

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

3. 注解主要屬性匯總

Extension 注解

ExtensionProperty 注解

4. 屬性詳解

4.1 Extension 注解相關屬性

name () 和 properties () 屬性

定義：

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

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

使用方法：

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

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

@ApiOperation(value = "user", 
            extensions = { 
            @Extension(name = "用戶登錄拓展參數(shù)", 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. 在實際項目開發(fā)中，一般具體的一個接口很少會出現(xiàn)拓展參數(shù)，如果存在，那也是通過業(yè)務需求來描述的，我們不能隨意編造任何拓展參數(shù)。

4.2 ExtensionProperty 注解相關屬性

name () 和 value () 屬性

定義：

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

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

使用方法：

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

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

代碼解釋：

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

Tips ：

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

5. 小結

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

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