从 API Gateway 导出 REST API - Amazon API Gateway

从 API Gateway 导出 REST API

使用 API Gateway 控制台或其他方式在 API Gateway 中创建和配置 REST API 后,您可以使用 API Gateway 导出 API(该 API 是 Amazon API Gateway 控制服务的一部分)将其导出到 OpenAPI 文件。要使用 API Gateway 导出 API,您需要签署您的 API 请求。有关签署请求的更多信息,请参阅《IAM 用户指南》中的签署 AWS API 请求。您可以在导出的 OpenAPI 定义文件中包含 API Gateway 集成扩展以及 Postman 扩展。

注意

使用 AWS CLI 导出 API 时,请务必包含扩展参数,如以下示例所示,以确保包含 x-amazon-apigateway-request-validator 扩展:

aws apigateway get-export --parameters extensions='apigateway' --rest-api-id abcdefg123 --stage-name dev --export-type swagger latestswagger2.json

如果 API 的负载并非 application/json 类型,则您无法将其导出。如果尝试导出,您将收到一条错误响应,指出未找到 JSON 正文模型。

请求导出 REST API

借助 Export API,您可以提交 GET 请求,将要导出的 REST 指定为 URL 路径的一部分,以此来导出现有 REST API。请求 URL 的格式如下:

OpenAPI 3.0
https://<host>/restapis/<restapi_id>/stages/<stage_name>/exports/oas30
OpenAPI 2.0
https://<host>/restapis/<restapi_id>/stages/<stage_name>/exports/swagger

您可以附加 extensions 查询字符串,以指定是否要包含 API Gateway 扩展(含 integration 值)或 Postman 扩展(含 postman 值)。

此外,您还可以将 Accept 标头设置为 application/jsonapplication/yaml,以分别接收 JSON 格式或 YAML 格式的 API 定义输出。

有关使用 API Gateway 导出 API 提交 GET 请求的更多信息,请参阅 GetExport

注意

如果您在 API 中定义模型,那么这些模型的内容类型必须为“application/json”,这样 API Gateway 才能将其导出。否则,API Gateway 会引发异常,并显示“仅找到适用于……的非 JSON 正文模型”的错误消息。

模型必须包含属性或者被定义为特定 JSONSchema 类型。

下载 JSON 格式的 REST API OpenAPI 定义

要下载 JSON 格式的 REST API OpenAPI 定义,请执行以下操作:

OpenAPI 3.0
GET /restapis/<restapi_id>/stages/<stage_name>/exports/oas30 Host: apigateway.<region>.amazonaws.com Accept: application/json
OpenAPI 2.0
GET /restapis/<restapi_id>/stages/<stage_name>/exports/swagger Host: apigateway.<region>.amazonaws.com Accept: application/json

这里的 <region> 可以是 (比如说) us-east-1。有关提供 API Gateway 的所有区域,请参阅 Regions and Endpoints

下载 YAML 格式的 REST API OpenAPI 定义

要下载 YAML 格式的 REST API OpenAPI 定义,请执行以下操作:

OpenAPI 3.0
GET /restapis/<restapi_id>/stages/<stage_name>/exports/oas30 Host: apigateway.<region>.amazonaws.com Accept: application/yaml
OpenAPI 2.0
GET /restapis/<restapi_id>/stages/<stage_name>/exports/swagger Host: apigateway.<region>.amazonaws.com Accept: application/yaml

借助 Postman 扩展下载 JSON 格式的 REST API OpenAPI 定义

借助 Postman 导出并下载 JSON 格式的 REST API OpenAPI 定义,请执行以下操作:

OpenAPI 3.0
GET /restapis/<restapi_id>/stages/<stage_name>/exports/oas30?extensions=postman Host: apigateway.<region>.amazonaws.com Accept: application/json
OpenAPI 2.0
GET /restapis/<restapi_id>/stages/<stage_name>/exports/swagger?extensions=postman Host: apigateway.<region>.amazonaws.com Accept: application/json

借助 API Gateway 集成下载 YAML 格式的 REST API OpenAPI 定义

要借助 API Gateway 集成导出并下载 YAML 格式的 REST API OpenAPI 定义,请执行以下操作:

OpenAPI 3.0
GET /restapis/<restapi_id>/stages/<stage_name>/exports/oas30?extensions=integrations Host: apigateway.<region>.amazonaws.com Accept: application/yaml
OpenAPI 2.0
GET /restapis/<restapi_id>/stages/<stage_name>/exports/swagger?extensions=integrations Host: apigateway.<region>.amazonaws.com Accept: application/yaml

使用 API Gateway 控制台导出 REST API

将 REST API 部署到一个阶段之后,您可以使用 API Gateway 控制台将此阶段中的 API 导出到 OpenAPI 文件。

在 API Gateway 控制台的阶段窗格中,选择阶段操作,然后选择导出

使用 API Gateway 控制台导出 REST API

指定 API 规范类型格式扩展以下载您 API 的 OpenAPI 定义。