Swagger UI访问带Basic Auth的OpenAPI端点不触发认证问题

我有一个JAX-RS应用，用OpenAPI/Swagger管理API文档。已通过Basic Auth保护OpenAPI端点（http://localhost:8090/openapi），首次请求该端点时，响应头会携带WWW-Authenticate: Basic realm="XXXX"。在Chrome浏览器直接打开该URL时，能正常弹出认证窗口；但通过Swagger UI访问时，不会触发用户名密码认证流程，直接显示401错误页面。

Swagger请求的响应头信息如下：

Content-Security-Policy:default-src 'none'; frame-ancestors 'none'
Content-Type:application/json
Referrer-Policy:strict-origin-when-cross-origin
Strict-Transport-Security:max-age=31536000
WWW-Authenticate: Basic realm="XXXX"
X-Content-Type-Options:nosniff
X-Frame-Options:SAMEORIGIN
X-Xss-Protection:1
Accept:application/json,*/*

Chrome浏览器效果：

Swagger UI效果：

1. 在OpenAPI规范中声明Basic Auth安全规则 #

让Swagger UI自动识别认证要求，需要在OpenAPI规范里明确定义Basic Auth安全方案，并全局启用：

方式1：通过OpenAPI配置文件（yaml/json） #

openapi: 3.0.3
info:
  title: 你的API文档标题
  version: 1.0.0
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
security:
  - BasicAuth: []  # 全局应用该安全策略

方式2：在JAX-RS代码中通过注解配置 #

在应用类上定义安全方案：

import io.swagger.v3.oas.annotations.security.SecurityScheme;
import io.swagger.v3.oas.annotations.security.SecuritySchemes;
import jakarta.ws.rs.ApplicationPath;
import jakarta.ws.rs.core.Application;

@SecuritySchemes({
    @SecurityScheme(
        name = "BasicAuth",
        type = SecurityScheme.Type.HTTP,
        scheme = "basic"
    )
})
@ApplicationPath("/")
public class YourJaxRsApplication extends Application {
    // 应用初始化逻辑
}

然后在OpenAPI端点的资源类上添加全局安全要求：

import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@SecurityRequirement(name = "BasicAuth")
@Path("/openapi")
public class OpenApiDocResource {
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public String getOpenApiSpecification() {
        // 返回生成的OpenAPI规范内容
        return "";
    }
}

2. 给Swagger UI添加响应拦截器处理401 #

如果上述配置无效，可以在Swagger UI的初始化代码中添加拦截逻辑，当检测到401响应且带有WWW-Authenticate头时，触发浏览器的认证弹窗：

const swaggerUi = SwaggerUIBundle({
  url: "http://localhost:8090/openapi",
  dom_id: '#swagger-ui',
  // 其他Swagger UI配置项...
  responseInterceptor: (response) => {
    if (response.status === 401 && response.headers['www-authenticate']) {
      // 弹出用户名密码输入框
      const username = prompt("请输入认证用户名");
      const password = prompt("请输入认证密码");
      if (username && password) {
        // 存储凭证并重新加载页面
        const authToken = btoa(`${username}:${password}`);
        localStorage.setItem('basicAuthToken', authToken);
        window.location.reload();
      }
    }
    return response;
  },
  requestInterceptor: (request) => {
    // 发起请求时自动携带已存储的认证头
    const authToken = localStorage.getItem('basicAuthToken');
    if (authToken) {
      request.headers.Authorization = `Basic ${authToken}`;
    }
    return request;
  }
});

3. 调整后端响应的内容类型 #

Chrome直接访问时会自动处理WWW-Authenticate头，但Swagger UI通过AJAX请求获取文档时，若后端返回的是application/json类型的401响应，Swagger UI不会触发浏览器的原生认证弹窗。可以调整后端逻辑：当检测到请求来自Swagger UI（通过User-Agent识别）时，返回text/html类型的响应，让浏览器触发认证流程。

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