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 注解及其常用属性时，各位同学注意斟酌这两个注解和权限控制框架之间的差异，要能够做到什么时候使用注解合适，什么时候使用权限控制框架合适。