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 {
/**
* 接口信息
*/
@Bean
public 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 等)。
*/
@Bean
public 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
参数。
无需鉴权接口处理
只需在添加鉴权参数前,排除那些无需鉴权的接口即可。
@Bean
public 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 🌺 |
本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。 如若内容造成侵权/违法违规/事实不符,请联系我的编程经验分享网邮箱:veading@qq.com进行投诉反馈,一经查实,立即删除!