Swagger-Extension 和 ExtensionProperty 注解

1. 前言

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

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

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

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

• Extension 注解的 name 、 properties ；

• ExtensionProperty 注解的 name 、 value 。

2. 什么是 Extension 和 ExtensionProperty 注解 ？

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

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

3. 注解主要屬性匯總

Extension 注解

ExtensionProperty 注解

4. 屬性詳解

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

name () 和 properties () 屬性

定義：

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

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

使用方法：

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

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

@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 注解及其相關(guān)屬性時(shí)，一定要看清楚該注解是通過哪種方法進(jìn)行使用的。
2. 在實(shí)際項(xiàng)目開發(fā)中，一般具體的一個(gè)接口很少會(huì)出現(xiàn)拓展參數(shù)，如果存在，那也是通過業(yè)務(wù)需求來描述的，我們不能隨意編造任何拓展參數(shù)。

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

name () 和 value () 屬性

定義：

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

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

使用方法：

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

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

5. 小結(jié)

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

在學(xué)習(xí) Extension 和 ExtensionProperty 注解及其常用屬性時(shí)，各位同學(xué)需要注解和其他注解搭配的使用方法，因?yàn)檫@兩個(gè)注解均不能單獨(dú)拿出來使用。