Swagger-Authorization 和 AuthorizationScope注解

1. 前言

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

Authorization 和AuthorizationScope 注解，在實際項目中很少用到，因為這兩個注解是和權限有關的，眾所周知，和權限有關的框架或者中間件成熟的已經有很多了，而 Swagger 更多的則是用來生成接口在線文檔，重點并不在權限控制上，所以我們只需要掌握他們最基本的用法和常用屬性即可。

重點講解的屬性：

• Authorization 注解的 value 、scopes 屬性；

• AuthorizationScope 注解的 scope 、 description 屬性。

2. 什么是 Authorization 和 AuthorizationScope 注解 ？

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

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

Authorization 和 AuthorizationScope 注解的關系并不像是一組關系緊密的注解，因為 Authorization 注解可以拋開 AuthorizationScope 注解使用。

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

3. 注解主要屬性匯總

Authorization 注解

AuthorizationScope 注解

4. 屬性詳解

4.1 Authorization 注解相關屬性

value() 屬性

定義：

該屬性就是對接口訪問權限添加一個名稱，即接口訪問權限的名稱是什么。

使用方法：

value 屬性的使用方法有些特殊，不能單獨使用，因為單獨使用時， Swagger 并不會解析該屬性，需要和 @ApiOperaion 注解和 @Api 注解一起搭配使用，這樣 Swagger 才會解析該注解。

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

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

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

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

代碼解釋：

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

顯示結果：

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

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

scopes() 屬性

定義：

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

使用方法：

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

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

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

@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 ： 在實際項目開發中，如果非要使用 Authorization 注解的 scopes 屬性來對接口進行權限控制，那么項目中必須要有 OAuth2 框架，但是往往此框架可以直接對接口進行權限控制，不需要再使用該注解進行配置了。

4.2 AuthorizationScope 注解相關屬性

scope() 和 description() 屬性

定義：

scope 屬性是用來描述訪問接口的權限的具體的一個范圍名稱，即描述接口訪問的單個權限名稱。

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

使用方法：

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

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

代碼解釋：

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

Tips ：

1. 在使用 AuthorizationScope 注解時，注意和 @ApiOperaion 注解的搭配，代碼格式稍微有些繞，同學們在學習時需要理清楚代碼格式。
2. AuthorizationScope 注解的兩個屬性經常用于在接口權限存在多條時使用，一般很少單獨使用。

5. 小結

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

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

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