章节索引 :

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 注解

属性名称 属性类型 默认值 作用
value() String 定义接口权限名称
scopes() AuthorizationScope[] @AuthorizationScope(scope = “”, description = “”) 定义接口权限范围

AuthorizationScope 注解

属性名称 属性类型 默认值 作用
scope() String 定义接口权限单独范围名称
description() String 定义接口权限单独范围的描述

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