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

2023-12-16 04:55:29

🚀 作者主页: 有来技术
🔥 开源项目: 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 微服务商城
GithubGitee
后端youlai-mall 🍃youlai-mall 🍃
前端mall-admin🌺mall-admin 🌺
移动端mall-app 🍌mall-app 🍌
  • SpringBoot 3+ Vue3 单体权限管理系统
GithubGitee
后端youlai-boot 🍃youlai-boot 🍃
前端vue3-element-admin 🌺vue3-element-admin 🌺

文章来源:https://blog.csdn.net/u013737132/article/details/135026363
本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。