Spring Boot集成Springdoc OpenAPI如何对API定义端点做安全防护？

这个需求完全可以实现，核心要做两处配置：Spring Security侧将API定义端点纳入鉴权范围，Springdoc侧配置Swagger UI拉取API定义时自动携带已输入的JWT令牌。

1. Spring Security 鉴权配置 #

首先确保你没有把springdoc.api-docs.path对应的路径配置为白名单，将其和业务接口一同纳入JWT校验范围，示例配置如下：

@Configuration
public class SecurityConfig {
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.authorizeRequests()
                // 如果你自定义了api-docs路径，这里替换为你的自定义路径
                .antMatchers("/v3/api-docs/**").authenticated()
                .antMatchers("/swagger-ui/**", "/swagger-ui.html").permitAll()
                .anyRequest().authenticated()
                // 后续补充你的JWT校验过滤器、csrf关闭等原有配置
                .oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt);
        return http.build();
    }
}

注意：Swagger UI本身的静态资源路径需要放开白名单，否则无法正常加载页面

2. Springdoc 自动携带令牌配置 #

你需要配置Swagger UI的请求拦截器，从本地存储中读取用户输入的JWT，在请求API定义端点时自动添加到请求头，可直接在application.yml中添加如下配置：

springdoc:
  swagger-ui:
    # 持久化用户输入的授权信息，刷新页面也不会丢失
    persist-authorization: true
    # 请求拦截器：自动给所有Swagger UI发起的请求添加Authorization头
    request-interceptor: "function(request) { 
      const authData = JSON.parse(window.localStorage.getItem('swagger-ui_auth'));
      if (authData?.authorized) {
        // 这里的bearerAuth要和你定义的JWT安全方案名称完全一致
        const token = authData.authorized['bearerAuth'].value;
        request.headers['Authorization'] = 'Bearer ' + token;
      }
      return request; 
    }"

如果你的安全方案是通过Java代码定义的，确保安全方案名称和上述配置中的bearerAuth一致，示例如下：

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .components(new Components()
                    .addSecuritySchemes("bearerAuth", new SecurityScheme()
                            .type(SecurityScheme.Type.HTTP)
                            .scheme("bearer")
                            .bearerFormat("JWT")));
}

生效验证 #

配置完成后重启服务：

1. 打开Swagger UI页面，点击Authorize按钮输入有效JWT
2. 刷新页面，此时Swagger UI拉取API定义的请求会自动携带Authorization头，即可正常加载接口文档，无需再单独配置白名单。

注意事项 #

• 如果你自定义了springdoc.api-docs.path配置，记得同步修改Spring Security配置中的鉴权路径
• 确保你的JWT校验过滤器没有排除API定义端点，会正常解析该路径请求的头信息
• 若Swagger UI为跨域部署，需要在跨域配置中允许Authorization头

内容的提问来源于stack exchange，提问作者Florian Beaufumé