如何为Swagger UI响应添加CORS头部？本地API跨域报错排查

问题根源 #

你之前在Swagger YAML里添加Access-Control-Allow-Origin头的位置错误——把它嵌套在了schema下面，违反了OpenAPI 3.0的规范，直接导致YAML文件无效。正确的位置应该是在响应对象的根层级，和description、content同级。

正确的OpenAPI配置方法 #

1. 修正单个接口的响应头位置 #

修改/Employees接口的200响应配置，将headers移到与content同级的位置：

responses:
  '200':
    description: OK.
    headers:
      Access-Control-Allow-Origin:
        schema:
          type: string
        description: 允许跨域请求的来源域名
    content:
      application/json:
        schema:
          type: array
          items:
            $ref: '#/components/schemas/Employees'

2. 处理CORS预请求（OPTIONS） #

浏览器发起跨域GET请求前，会先发OPTIONS预请求验证权限，你可以二选一处理：

• 方式一：AWS API Gateway自动配置
  直接在API Gateway控制台开启CORS，它会自动生成OPTIONS方法并配置对应的响应头，无需手动在OpenAPI中编写。
• 方式二：OpenAPI手动定义OPTIONS接口
  如果需要通过OpenAPI统一管理，给/Employees添加OPTIONS方法：

paths:
  /Employees:
    get:
      # 原GET接口配置保持不变
    options:
      summary: 处理CORS预请求
      responses:
        '200':
          description: 预请求响应
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
            Access-Control-Allow-Methods:
              schema:
                type: string
                example: GET, OPTIONS
            Access-Control-Allow-Headers:
              schema:
                type: string
                example: Authorization, Content-Type
          content:
            application/json:
              schema:
                type: object

3. 同步AWS API Gateway的CORS设置 #

确保API Gateway的CORS配置与OpenAPI一致：

• 允许的Origin：设置为Swagger UI所在的域名（比如http://localhost:3000，生产环境避免用*）
• 允许的Headers：包含你的API需要的头，比如Authorization
• 允许的Methods：包含GET、OPTIONS等你用到的方法

验证步骤 #

配置完成后重新部署API Gateway，再用Swagger UI测试。若仍报错，检查浏览器开发者工具的网络请求：

• 确认OPTIONS请求的响应头包含Access-Control-Allow-Origin
• 确认GET请求的响应头也存在该字段

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