Swagger-Authorization 和 AuthorizationScope注解

1. 前言

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

Authorization 和AuthorizationScope 注解，在實(shí)際項(xiàng)目中很少用到，因?yàn)檫@兩個(gè)注解是和權(quán)限有關(guān)的，眾所周知，和權(quán)限有關(guān)的框架或者中間件成熟的已經(jīng)有很多了，而 Swagger 更多的則是用來生成接口在線文檔，重點(diǎn)并不在權(quán)限控制上，所以我們只需要掌握他們最基本的用法和常用屬性即可。

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

• Authorization 注解的 value 、scopes 屬性；

• AuthorizationScope 注解的 scope 、 description 屬性。

2. 什么是 Authorization 和 AuthorizationScope 注解 ？

Authorization 注解是作用在接口方法上的注解，用來對該接口方法的訪問權(quán)限進(jìn)行控制，即給該接口方法添加的額外權(quán)限是什么，一般不會單獨(dú)使用，經(jīng)常和 @ApiOperation 注解或者 @Api 注解搭配使用 。

AuthorizationScope 注解也是作用在接口方法上的注解，作用和 @Authorization 注解類似，他是用來描述接口權(quán)限的一個(gè)范圍，即定義該接口的權(quán)限范圍是什么。

Authorization 和 AuthorizationScope 注解的關(guān)系并不像是一組關(guān)系緊密的注解，因?yàn)?Authorization 注解可以拋開 AuthorizationScope 注解使用。

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

3. 注解主要屬性匯總

Authorization 注解

AuthorizationScope 注解

4. 屬性詳解

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

value() 屬性

定義：

該屬性就是對接口訪問權(quán)限添加一個(gè)名稱，即接口訪問權(quán)限的名稱是什么。

使用方法：

value 屬性的使用方法有些特殊，不能單獨(dú)使用，因?yàn)閱为?dú)使用時(shí)， Swagger 并不會解析該屬性，需要和 @ApiOperaion 注解和 @Api 注解一起搭配使用，這樣 Swagger 才會解析該注解。

但是使用該屬性所描述的值并不會顯示在界面上，只會顯示一個(gè)標(biāo)志，表明該接口方法具有 Swagger 的權(quán)限控制策略，如果想要在界面上調(diào)試該接口需要一定的權(quán)限。

這里以 @ApiOperaion 注解為例，在 ApiOperaion 注解中直接聲明 authorizations 屬性的值即可，authorizations 的值是一個(gè) Authorization 類型的數(shù)組。

例如，對于用戶登錄接口，我想添加一個(gè)名稱為’普通用戶可訪問‘的權(quán)限名稱，我們可以這樣寫：authorizations = { @Authorization(value = “普通用戶可訪問”) （現(xiàn)在你不需要理解業(yè)務(wù)代碼代表什么意思，重點(diǎn)看所使用的注解及屬性即可，下同）。

@ApiOperation(value = "userlogin", authorizations = { @Authorization(value = "普通用戶可訪問") })
public ServerResponse<User> login(User user){
    // do something...
} 

代碼解釋：

1-3 行，我們在用戶登錄接口方法的上方定義了 ApiOperation 注解的 authorizations 屬性，其值為 Authorization 注解的 value 屬性所描述。

顯示結(jié)果：

可以看到，在紅色箭頭所指的右上角位置有一個(gè)鎖的圖片，這個(gè)鎖的圖片就是我們使用 Authorization 注解的 value 屬性所展示的效果了。

Tips ： 在使用 Authorization 注解的 value 屬性前需要在 Swagger 的配置類中取配置和權(quán)限有關(guān)的 schema ，如果不配置的話，就不能對接口進(jìn)行權(quán)限控制，由于本門課程針對 Swagger 初學(xué)者，所以這里就不再介紹了，感興趣的可以自行查閱資料了解。

scopes() 屬性

定義：

該屬性就是對接口權(quán)限的范圍做一個(gè)描述，即描述該接口都可以允許哪些權(quán)限訪問，超過這個(gè)權(quán)限就不能訪問該接口。

使用方法：

scopes 屬性的使用方法和 value 屬性的使用方法相同，這里還以 @ApiOperation 屬性為例，詳細(xì)代碼如下所示。

由于 scopes 屬性的值是使用 AuthorizationScope 注解來描述，且 AuthorizationScope 注解的使用要求項(xiàng)目中必須要用到 OAuth2 框架，所以 scopes 屬性的描述也要求項(xiàng)目中必須要用到 OAuth2 框架，OAuth2 框架的使用不在本門課程內(nèi)，所以這里就不再演示了。

綜上所述，同學(xué)們只需要知道這個(gè)屬性的基本作用和基本用法即可。

@ApiOperation(value = "userlogin", authorizations = { @Authorization(scopes = { @AuthorizationScope(scope = "普通用戶", description = "common user") } })
public ServerResponse<User> login(User user){
    // do something...
} 

代碼解釋：

1-3行，我們在用戶登錄接口方法的上方定義了 ApiOperation 注解的 authorizations 屬性，其值為 Authorization 注解的 scopes 屬性所描述。

Tips ： 在實(shí)際項(xiàng)目開發(fā)中，如果非要使用 Authorization 注解的 scopes 屬性來對接口進(jìn)行權(quán)限控制，那么項(xiàng)目中必須要有 OAuth2 框架，但是往往此框架可以直接對接口進(jìn)行權(quán)限控制，不需要再使用該注解進(jìn)行配置了。

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

scope() 和 description() 屬性

定義：

scope 屬性是用來描述訪問接口的權(quán)限的具體的一個(gè)范圍名稱，即描述接口訪問的單個(gè)權(quán)限名稱。

description 屬性就是對這個(gè)單個(gè)的權(quán)限名稱做一個(gè)簡短的描述，來解釋說明這個(gè)權(quán)限所代表的意思。

使用方法：

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

@ApiOperation(value = "userlogin", authorizations = { @Authorization(scopes = { @AuthorizationScope(scope = "普通用戶", description = "common user") } })
public ServerResponse<User> login(User user){
    // do something...
} 

代碼解釋：

我們可以看到，AuthorizationScope 注解中屬性的使用方法代碼和 Authorization 中的是完全相同的，這就說明：如果想對接口方法定義訪問權(quán)限范圍，則必須要使用 AuthorizationScope 注解才行，這里不再贅述。

Tips ：

1. 在使用 AuthorizationScope 注解時(shí)，注意和 @ApiOperaion 注解的搭配，代碼格式稍微有些繞，同學(xué)們在學(xué)習(xí)時(shí)需要理清楚代碼格式。
2. AuthorizationScope 注解的兩個(gè)屬性經(jīng)常用于在接口權(quán)限存在多條時(shí)使用，一般很少單獨(dú)使用。

5. 小結(jié)

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

無論是 Authorization 注解，還是 AuthorizationScope 注解，都是用來對接口的控制訪問權(quán)限添加額外的描述，而且 AuthorizationScope 注解中屬性的使用還需要項(xiàng)目中必須用到 OAuth2 框架，所以我建議：項(xiàng)目中如果需要對接口添加訪問權(quán)限控制，那就直接使用權(quán)限控制框架就好了。

在學(xué)習(xí) Authorization 和 AuthorizationScope 注解及其常用屬性時(shí)，各位同學(xué)注意斟酌這兩個(gè)注解和權(quán)限控制框架之間的差異，要能夠做到什么時(shí)候使用注解合適，什么時(shí)候使用權(quán)限控制框架合適。