如何在OpenAPI规范中为AWS API Gateway的响应模型指定名称

核心方案 #

避免依赖API Gateway自动从响应生成模型，改为在OpenAPI规范中显式定义模型并直接引用，这样部署时网关会严格使用你指定的模型名称，不会随机重命名。

具体操作步骤 #

• 在OpenAPI的components/schemas区块中提前定义所有需要的响应模型，指定明确的名称：

  components:
    schemas:
      UserDetailResponse:
        type: object
        properties:
          userId:
            type: string
          userName:
            type: string
          email:
            type: string
  

• 在API路径的响应配置中，通过$ref直接引用预定义的模型，而非仅内联schema结构：

  paths:
    /users/{userId}:
      get:
        responses:
          '200':
            description: 获取用户详情成功
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/UserDetailResponse'
  

• 将包含完整显式模型定义的OpenAPI规范嵌入SAM模板的AWS::Serverless::Api资源的DefinitionBody中。

注意事项 #

• 若之前存在自动生成的随机命名模型，建议先清理API Gateway中的旧模型，避免命名冲突。
• 确保OpenAPI规范的components/schemas部分完整覆盖所有需要的响应结构，不要遗漏。
• 部署完成后导出API时，模型名称会与你在OpenAPI中定义的完全一致，不会再出现随机变更的情况。

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