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

news2025/10/31 22:36:02

🚀 作者主页：有来技术
🔥 开源项目： 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))
                            );
                });
            }
        };
    }