Swagger 注解 @Authorization 和 @AuthorizationScope 的用法

@Authorization 和@AuthorizationScope 是 Swagger 提供的两个安全性相关的注解，用于在 Swagger UI 界面添加安全授权信息。

@Authorization 用于声明整个 API 所需的授权信息。它通常加在 Controller 类上，表示访问该 Controller 中的所有接口都需要授权。@AuthorizationScope 用于声明单个接口所需的授权作用域。它通常加在接口方法上，表示访问该接口需要具备的权限。

这两个注解的作用是让 Swagger 文档中能自动生成安全授权信息，开发者可以在 Swagger UI 中直接授权后调用接口，无需自己处理授权逻辑。

使用场景

@Authorization 和@AuthorizationScope 常用于以下场景：

• 接口需要不同的权限才能访问时，通过@AuthorizationScope 注解声明每个接口所需的授权作用域。
• 所有接口访问都需要相同的权限时，可以在 Controller 类上使用@Authorization 统一声明。
• 部分接口不需要授权就可以访问，这时通过选择性使用注解来声明需要授权的接口。
• 需要在 Swagger 文档中自动生成授权信息，方便使用者直接在 Swagger UI 中授权调用。
  

用法介绍

@Authorization 用法

@Authorization 用于声明整个 API 或 Controller 所需的授权信息。它通常加在 Controller 类上,表示访问该 Controller 中的所有接口都需要授权。

@Authorization 的主要属性如下:

使用示例:

@Authorization(value = "oauth2")
@Api(tags = "用户管理")
@RestController
@RequestMapping("/users")
public class UserController {

  @GetMapping
  public ResponseEntity<List<User>> getUsers() {
    // ...
  }

}

上例中添加了@Authorization 注解,表示该 UserController 中的所有接口访问都需要"oauth2"授权。

@AuthorizationScope 用法

@AuthorizationScope 用于声明单个接口所需的授权作用域。它通常加在接口方法上,表示访问该接口需要具备的权限。

@AuthorizationScope 的主要属性如下:

使用示例:

@GetMapping("/{id}")
@AuthorizationScope(scope = "read:user")
public UserDTO getUserById(@PathVariable Long id) {
  // ...
}

上例中添加了@AuthorizationScope 注解,表示访问该接口需要"read:user"权限。

实践案例

以下是在 SpringBoot 项目中的例子：

1. 添加 Maven 依赖

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-boot-starter</artifactId>
  <version>3.0.0</version>
</dependency>

2. 在 SpringBoot 应用主类添加@EnableOpenApi 注解

3. 在 Controller 类上添加@Authorization 声明授权方案

@Authorization("oauth2")
@RestController
public class UserController {

  @GetMapping("/users")
  public List<User> listUsers() {
    // ...
  } 

}

4. 在接口方法上添加@AuthorizationScope 声明授权作用域

@GetMapping("/{id}")
@AuthorizationScope(scope = "read:user")
public UserDTO getUserById(@PathVariable Long id) {
  // ...
}

5. 启动应用，在 Swagger UI 中可以看到授权信息，并使用"Authorize"按钮授权后调用接口

注意事项

• Swagger 只生成文档信息，不实现实际的授权逻辑，这需要自己实现。
• @Authorization 和@AuthorizationScope 中的授权方案名称要与实际一致。
• 授权作用域名称不要包含空格或特殊字符。
• Swagger 3.0 中需要同时添加 springfox-boot-starter 和 springdoc-openapi-ui 依赖。
  

常见问题

Q: Swagger UI 中没有显示授权信息？

A: 需要同时添加@EnableOpenApi 注解启用 Swagger。

Q: 授权不生效，接口仍然访问不了？

A: Swagger 只生成文档，实际的授权逻辑需要自己实现，如使用 Spring Security。

Swagger 和 Apifox 整合

Swagger 管理接口有时很不方便，缺乏一定的安全性和团队间的分享协作，所以我更推荐使用 Apifox 的 IDEA 插件。你可以在 IDEA 中自动同步 Swagger 注解到 Apifox，一键生成接口文档，多端同步，非常方便测试和维护，这样就可以迅速分享 API 给其他小伙伴。

Apifox 是一个比 Postman 更强大的接口测试工具，Apifox = Postman + Swagger + Mock + JMeter，Apifox 支持调试 http（s）、WebSocket、Socket、gRPC、Dubbo 等协议的接口，并且集成了 IDEA 插件。

Apifox 的 IDEA 插件可以自动解析代码注释，并基于 Javadoc、KDoc 和 ScalaDoc 生成 API 文档。通过 IntelliJ IDEA 的 Apifox Helper 插件，开发人员可以在不切换工具的情况下将他们的文档与 Apifox 项目同步。

当在 IDEA 项目中有接口信息变动，只需右键点击「 Upload to Apifox」一键即可完成同步，无需奔走相告。团队成员可在 Apifox 中看到同步后的最新内容。

现在出发去 JetBrains 插件市场 下载试试吧！或直接在 IDEA 内 「plugin」入口直接搜索 Apifox Helper。

知识扩展：

• 如何使用 Swagger 生成 Node.js API 文档
• 如何用 Swagger UI 和 JSDoc 编写 Express API 文档

参考链接：

Swagger Authorization 文档：https://swagger.io/docs/specification/authentication/

Springfox Authorization 示例：https://springfox.github.io/springfox/docs/snapshot/#auth-support

Springdoc Authorization 示例：https://springdoc.org/v2/#authorization