如何通过Terraform激活AWS API Gateway的文档版本？

aws_api_gateway_documentation_version仅负责创建文档版本的快照，不会自动将其设为Active状态。要让文档版本在对应API Stage中处于激活状态，需要通过aws_api_gateway_deployment资源关联该版本。

解决方案 #

在你的Terraform配置中，为API部署资源添加documentation_version参数，指向已创建的文档版本：

# 原文档版本配置（保持不变）
resource "aws_api_gateway_documentation_version" "docs_version" {
  version     = "v1.0.0-${var.env}"
  rest_api_id = aws_api_gateway_rest_api.my_api.id
  description = "Documentation for my API"
  depends_on  = [
    aws_api_gateway_documentation_part.method_docs
  ]
}

# 部署API并关联激活文档版本（新增或修改现有部署）
resource "aws_api_gateway_deployment" "api_deployment" {
  rest_api_id = aws_api_gateway_rest_api.my_api.id
  stage_name  = var.env

  # 关联文档版本，标记为当前Stage的Active版本
  documentation_version = aws_api_gateway_documentation_version.docs_version.version

  # 可选：文档内容更新时自动触发重新部署
  triggers = {
    documentation_change = sha1(jsonencode(aws_api_gateway_documentation_part.method_docs))
  }
}

关键说明 #

• documentation_version字段会在部署API时，将指定的文档版本设为对应Stage的Active状态，此时导出Swagger就能包含该版本的文档内容。
• 若已有现成的aws_api_gateway_deployment资源，只需在其中添加documentation_version参数即可，无需新建部署资源。
• 触发器配置是可选的，作用是当aws_api_gateway_documentation_part的内容更新时，自动触发API重新部署，确保Active文档版本同步更新。

内容的提问来源于stack exchange，提问作者José Daniel Montoya Salazar