Open API 中指定的文档不会从 AWS API Gateway 导出答案

【问题标题】：Documentation specified in Open API does not export from AWS API GatewayOpen API 中指定的文档不会从 AWS API Gateway 导出
【发布时间】：2026-01-20 02:55:02
【问题描述】：

我通过 Open API 规范指定我的 AWS API Gateway API。规范包含大量文档，我希望客户端开发人员在与 API 集成时使用这些文档。但是，我们添加到 Open API 规范的文档似乎没有从 API Gateway 导出，因此无法使用。

如前所述，我从 JSON 中的开放 API 规范开始。我使用 CloudFormation AWS::ApiGateway::RestApi 资源将其导入 API Gateway。

在此之后，我将 API 部署到一个阶段，最后，使用 aws cli 从此 API+阶段导出文档：

aws apigateway get-export \
    --parameters extensions='documentation' \
    --rest-api-id abc123 \
    --stage-name api \
    --export-type swagger \
    ./docs.json

此导出似乎缺少许多重要的文档属性，例如 description 和 pattern。

我的 API 中的示例 Open API 参数：

{
    in: 'path',
    name: 'service',
    type: 'string',
    required: true,
    pattern: '^[-a-zA-Z0-9]+$',
    description: 'Name of the Service (document) to retrieve.'
}

当我使用上面的 aws-cli 命令导出它时，我得到：

{
    "name" : "service",
    "in" : "path",
    "required" : true,
    "type" : "string"
}

description 和 pattern 属性都已从文档导出中删除，这很糟糕，因为它们确实是此参数文档的主要部分。

另外值得一提的是，如果我在 AWS 控制台（Swagger+API 网关扩展）中导出相同的 API，我会得到与从文档导出中所做的相同的参数定义。

还可能值得一提的是，这些集成都基于 Lambda 代理，如果这有所作为的话。

【问题讨论】：

标签： amazon-web-services aws-api-gateway

【解决方案1】：

导入 Swagger 模板后，API Gateway 会将 API 定义及其文档拆分为两个单独的实体。这允许您独立修改和部署两者。

导出功能仅导出部署到阶段的任何内容。导入 Swagger 模板将导致 API 定义和文档部分都被导入。但是，您似乎只部署了 API 定义。您必须先明确发布文档，然后才能在导出中使用它。

正如您所指出的，您还可以使用 CLI 发布新版本的文档：

aws apigateway create-documentation-version \ --rest-api-id abc123 \ --documentation-version 1 \ --stage-name api

【讨论】：

【解决方案2】：

在 API Gateway 团队的帮助下，这个问题已经得到解决。

我的工作流程中似乎缺少一个步骤。部署 API 后，必须部署文档：

aws apigateway create-documentation-version \
    --rest-api-id abc123 \
    --documentation-version 1 \
    --stage-name api

执行此操作后，导出命令将生成文档，而不是之前显示的 API 定义。

【讨论】：