Open API中指定的文档不从AWS API Gateway

Question

我通过Open API规范指定了我的AWS API网关API。规范包含许多文档，我希望客户端开发人员在与API集成时使用。但是，我们添加到Open API规范的文档似乎不是从API网关导出的，因此无法使用。

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

在此之后，我将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代理。

Answer 1

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

导出功能仅导出部署到舞台的任何内容。导入Swagger模板将导致导入API定义和文档部分。但是，您似乎只部署了API定义。您必须在文档在导出中可用之前明确发布文档。

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

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

Answer 2

在API网关团队的帮助下，这已得到解决。

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

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

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