在Swagger中配置API Gateway的Strict-Transport-Security报头遇错求助

错误原因分析 #

报错Invalid mapping expression parameter specified: method.response.header.Strict-Transport-Security主要由两个问题导致：

• 你当前使用的是aws_proxy集成类型，这种模式下API Gateway会直接转发Lambda的完整响应（包括头、状态码、内容），集成响应里的responseParameters配置完全不生效。
• 即便不用代理模式，你也没在对应方法的响应定义（比如200状态码）里提前声明Strict-Transport-Security这个响应头，API Gateway找不到对应参数，因此报错。

解决方案 #

方案一：保留aws_proxy模式（推荐） #

直接在Lambda函数的返回响应中添加HSTS头，API Gateway会自动转发这个头给客户端。示例Python代码：

import json

def lambda_handler(event, context):
    return {
        "statusCode": 200,
        "headers": {
            "Strict-Transport-Security": "max-age=31536000; includeSubdomains; preload",
            "Content-Type": "application/json"
        },
        "body": json.dumps({"id": "317d0a1d-1a44-4a47-b2d8-cbe64665591c", "name": "Josiah Morrow"})
    }

这种方式不需要修改OpenAPI定义，符合Lambda代理集成的使用习惯。

方案二：切换为非代理集成模式 #

如果必须在OpenAPI定义中配置头，需要修改两处：

1. 在方法的responses节点下，给需要返回HSTS头的状态码（比如200）添加响应头声明：

responses:
  "200":
    description: user returned successfully
    headers:
      Strict-Transport-Security:
        description: HSTS security header
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/User"

2. 修改集成类型为aws（移除proxy后缀），并确保集成响应的参数映射正确：

x-amazon-apigateway-integration:
  uri:
    Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${apiLambda.Arn}/invocations
  responses:
    default:
      statusCode: "200"
      responseParameters:
        method.response.header.Strict-Transport-Security: "'max-age=31536000; includeSubdomains; preload'"
  passthroughBehavior: "never"
  httpMethod: "POST"
  type: "aws"

注意：切换为非代理模式后，Lambda的返回格式必须符合API Gateway要求（如{"statusCode":200,"body":"xxx"}），API Gateway会负责处理响应映射和头信息返回。

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