Payara Micro配置OpenAPI CORS解决Swagger-UI跨域报错问题

环境与故障表现 #

• 服务端版本：Payara Micro 5.2021.9，微服务部署在Vagrant虚拟机内，监听地址10.0.2.15:8080
• 客户端版本：Swagger-UI 4.1.3，部署在宿主机，访问地址localhost:8080
• 故障现象：Swagger-UI加载服务OpenAPI规范时持续提示Possible cross-origin (CORS) issue跨域错误，该问题在Vagrant跨网络访问、Docker容器部署场景下均可稳定复现。

排查结论 #

• 按常规配置开启Payara Micro的OpenAPI CORS支持后，接口已正常返回CORS类响应头，但仍无法通过跨域校验
• 对比Swagger-UI的CORS头要求与接口实际返回值，核心差异为实际返回的Access-Control-Allow-Headers字段缺失api_key自定义头：

  Swagger-UI 要求的CORS响应头规则：

  Access-Control-Allow-Origin: *
  Access-Control-Allow-Methods: GET, POST, DELETE, PUT, PATCH, OPTIONS
  Access-Control-Allow-Headers: Content-Type, api_key, Authorization
  

  OpenAPI端点实际返回的响应头：

  Access-Control-Allow-Origin: *
  Access-Control-Allow-Headers: origin, content-type, accept, authorization
  Access-Control-Allow-Credentials: true
  Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS, HEAD
  

• 根因：Payara Micro默认内置的OpenAPI CORS配置未覆盖Swagger-UI请求携带的api_key头，浏览器OPTIONS预检请求校验失败，拦截了后续实际接口请求。

可行修复方案 #

方案1：启动参数自定义CORS规则（无代码侵入，推荐） #

启动Payara Micro时追加CORS配置参数，显式补全允许的请求头与请求方法：

java -jar payara-micro-5.2021.9.jar \
  --deploy your-microservice.war \
  --corsheaders "origin, content-type, accept, authorization, api_key" \
  --corsmethods "GET, POST, PUT, DELETE, OPTIONS, HEAD, PATCH"

配置生效后重新请求/openapi端点，确认响应头中Access-Control-Allow-Headers已包含api_key字段即可。

方案2：全局JAX-RS响应过滤器（灵活度高） #

如果需要对服务内所有接口统一配置CORS规则，可在业务代码中新增全局响应过滤器，无需修改启动命令：

import javax.ws.rs.container.ContainerRequestContext;
import javax.ws.rs.container.ContainerResponseContext;
import javax.ws.rs.container.ContainerResponseFilter;
import javax.ws.rs.ext.Provider;
import java.io.IOException;

@Provider
public class GlobalCorsFilter implements ContainerResponseFilter {
    @Override
    public void filter(ContainerRequestContext requestContext, ContainerResponseContext responseContext) throws IOException {
        responseContext.getHeaders().putSingle("Access-Control-Allow-Origin", "*");
        responseContext.getHeaders().putSingle("Access-Control-Allow-Headers", "origin, content-type, accept, authorization, api_key");
        responseContext.getHeaders().putSingle("Access-Control-Allow-Credentials", "true");
        responseContext.getHeaders().putSingle("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS, HEAD, PATCH");
    }
}

重新编译打包服务部署即可生效，该配置优先级高于Payara内置的CORS规则，可覆盖包括OpenAPI在内的所有接口响应头。

验证方式 #

配置完成后清空浏览器缓存，重新打开Swagger-UI页面即可正常加载OpenAPI规范。也可通过curl发送OPTIONS预检请求，确认响应头符合要求后再验证页面访问。

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