如何在Spring Cloud Gateway中自定义SpringDoc OpenApi并添加全局安全Schema

你的配置已经在OpenAPI的Components里定义了Bearer JWT的安全Schema，但缺少全局安全要求的配置，导致这个认证规则没被应用到所有接口，也不会在文档顶部显示预期的"Authorize"入口。另外你的GroupedOpenApi配置里pathsToMatch写的是OpenAPI文档的路径，不是业务接口路径，会导致分组无法正确包含服务接口。

修改后的完整配置代码 #

@Configuration
public class OpenApiConfig {

    @Bean
    public GroupedOpenApi apis(OpenApiCustomizer openApiCustomizer) {
        return GroupedOpenApi.builder()
                .group("notifications")
                .pathsToMatch("/notifications/**") // 改为实际业务接口路径前缀
                .addOpenApiCustomizer(openApiCustomizer)
                .build();
    }

    @Bean
    public OpenApiCustomizer openApiCustomizer() {
        Info apiInfo = new Info()
                .title(OpenApiDesc.API_TITLE)
                .version(OpenApiDesc.API_VERSION)
                .contact(new Contact())
                .description(OpenApiDesc.API_DESCRIPTION)
                .termsOfService(OpenApiDesc.API_TERMS_OF_SERVICE)
                .license(new License());
                
        // 定义Bearer JWT安全Schema
        SecurityScheme bearerScheme = new SecurityScheme()
                .type(SecurityScheme.Type.HTTP)
                .scheme("bearer")
                .bearerFormat("JWT");
                
        // 创建全局安全要求，绑定定义好的Schema
        SecurityRequirement securityRequirement = new SecurityRequirement().addList("bearer-key");

        return openApi -> openApi
                .info(apiInfo)
                .components(new Components().addSecuritySchemes("bearer-key", bearerScheme))
                .security(List.of(securityRequirement)); // 全局启用该认证规则
    }
}

关键修改说明 #

• 修正路径匹配规则：把pathsToMatch改为业务接口的路径前缀，确保分组能正确包含所有需要展示的接口。
• 添加全局安全要求：通过openApi.security()方法将"bearer-key"设置为全局默认认证规则，这样所有接口会自动关联该认证，同时文档顶部会出现预期的"Authorize"按钮。

如果不需要所有接口强制使用该认证，仅需提供认证选项，可以去掉.security(List.of(securityRequirement))，然后在需要认证的接口上单独添加@SecurityRequirement(name = "bearer-key")注解即可。

内容的提问来源于stack exchange，提问作者Willbeplay