Knife4j 接口文档如何设置 Authorization 鉴权参数?

🚀 作者主页： 有来技术
🔥 开源项目： youlai-mall 🍃 vue3-element-admin 🍃 youlai-boot
🌺 仓库主页： Gitee 💫 Github 💫 GitCode
💖 欢迎点赞 👍 收藏 ⭐留言 📝 如有错误敬请纠正！

前言

在开发中，API鉴权是一个重要的安全机制，确保只有合法的用户可以访问受保护的资源。在使用 Spring Boot 和 Knife4j（OpenAPI）构建 API 时，我们常常需要在每个接口的请求头中添加Authorization参数，以进行身份验证。在本文中，将介绍如何通过配置，实现全局添加 Authorization 参数，同时处理无需鉴权的特殊接口。

期望描述

在所有需要鉴权接口请求头添加 Authorization 参数，如下图所示：

单个设置 Authorization

需要在接口添加 @SecurityRequirement(name = "Authorization") 注解，示例代码如下：

    @PostMapping@Operation(summary = "文件上传", security = {@SecurityRequirement(name = "Authorization")})// @SecurityRequirement(name = HttpHeaders.AUTHORIZATION) // 或者这种添加鉴权参数public Result<FileInfo> uploadFile(@Parameter(description ="表单文件对象") @RequestParam(value = "file") MultipartFile file) {FileInfo fileInfo = ossService.uploadFile(file);return Result.success(fileInfo);}

单个设置需要在每个接口添加 @SecurityRequirement 注解，项目接口太多很不方便。

全局设置 Authorization

开发者可以借助 GlobalOpenApiCustomizer 接口，给某一个 OpenAPI 实例分组下的所有接口添加鉴权方案，代码如下：

完整代码: SwaggerConfig.java

package com.youlai.system.config;import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springdoc.core.customizers.GlobalOpenApiCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpHeaders;/*** Swagger 配置* <p>** @author haoxr* @see <a href="https://doc.xiaominfo.com/docs/quick-start">knife4j 快速开始</a>* @since 2023/2/17*/
@Configuration
@Slf4j
@RequiredArgsConstructor
public class SwaggerConfig {/*** 接口信息*/@Beanpublic OpenAPI openApi() {return new OpenAPI().info(new Info().title("youlai-boot 接口文档").version("2.5.1"))// 配置全局鉴权参数-Authorize.components(new Components().addSecuritySchemes(HttpHeaders.AUTHORIZATION,new SecurityScheme().name(HttpHeaders.AUTHORIZATION).type(SecurityScheme.Type.APIKEY).in(SecurityScheme.In.HEADER).scheme("Bearer").bearerFormat("JWT")));}/*** 全局自定义扩展* <p>* 在OpenAPI规范中，Operation 是一个表示 API 端点（Endpoint）或操作的对象。* 每个路径（Path）对象可以包含一个或多个 Operation 对象，用于描述与该路径相关联的不同 HTTP 方法（例如 GET、POST、PUT 等）。*/@Beanpublic GlobalOpenApiCustomizer globalOpenApiCustomizer() {return openApi -> {// 全局添加鉴权参数if (openApi.getPaths() != null) {openApi.getPaths().forEach((s, pathItem) -> {// 接口添加鉴权参数pathItem.readOperations().forEach(operation ->operation.addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION)));});}};}}

全局设置会有个问题，就是那些无需鉴权的接口 (登录、获取验证码) 也会添加 Authorization 参数。

无需鉴权接口处理

只需在添加鉴权参数前，排除那些无需鉴权的接口即可。

 	@Beanpublic GlobalOpenApiCustomizer globalOpenApiCustomizer() {return openApi -> {// 全局添加鉴权参数if (openApi.getPaths() != null) {openApi.getPaths().forEach((s, pathItem) -> {// 登录接口/验证码不需要添加鉴权参数if (s.equals("/api/v1/auth/login") || s.equals("/api/v1/auth/captcha")) {return;}// 接口添加鉴权参数pathItem.readOperations().forEach(operation ->operation.addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION)));});}};}

参考文档

OpenAPI3规范中添加Authorization鉴权请求Header不生效？

结语

通过使用 OpenAPI 的全局配置，实现了在所有需要鉴权的接口请求头中添加 ``Authorization 参数的目标。同时，通过排除无需鉴权的接口，确保了对安全性要求不同的接口进行了灵活的处理。

开源项目

• SpringCloud + Vue3 微服务商城

	Github	Gitee
后端	youlai-mall 🍃	youlai-mall 🍃
前端	mall-admin🌺	mall-admin 🌺
移动端	mall-app 🍌	mall-app 🍌

• SpringBoot 3+ Vue3 单体权限管理系统

	Github	Gitee
后端	youlai-boot 🍃	youlai-boot 🍃
前端	vue3-element-admin 🌺	vue3-element-admin 🌺