Amazon API Gateway
开发人员指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

导入 API 文档

与导入 API 实体定义一样,您可以在 API Gateway 中将文档部分从外部 OpenAPI 文件导入到 API 中。您需要在有效的 OpenAPI 定义文件中指定 x-amazon-apigateway-documentation 对象 扩展中待导入的文档部分。导入文档的过程不会更改现有的 API 实体定义。

您可以选择在 API Gateway 中将新指定的文档部分合并到现有的文档部分中,也可以覆盖现有的文档部分。在 MERGE 模式下,在 OpenAPI 文件中定义的新文档部分会添加到 API 的 DocumentationParts 集合中。如果存在已导入的 DocumentationPart,在两者属性不同的情况下,导入的属性将替代现有属性。其他现有的文档属性不受影响。在 OVERWRITE 模式中,整个 DocumentationParts 集合将被替代,具体取决于导入的 OpenAPI 定义文件。

使用 API Gateway REST API 导入文档部分

要使用 API Gateway REST API 导入 API 文档,请调用 documentationpart:import 操作。以下示例显示了如何使用单个 GET / 方法覆盖 API 的现有文档部分,并在成功后返回 200 OK 响应。

OpenAPI 3.0OpenAPI 2.0
OpenAPI 3.0
PUT /restapis/<restapi_id>/documentation/parts&mode=overwrite&failonwarnings=true Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "openapi": "3.0.0", "info": { "description": "description", "version": "1", "title": "doc" }, "paths": { "/": { "get": { "description": "Method description.", "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } } } } } }, "x-amazon-apigateway-documentation": { "version": "1.0.3", "documentationParts": [ { "location": { "type": "API" }, "properties": { "description": "API description", "info": { "description": "API info description 4", "version": "API info version 3" } } }, { "location": { "type": "METHOD", "method": "GET" }, "properties": { "description": "Method description." } }, { "location": { "type": "MODEL", "name": "Empty" }, "properties": { "title": "Empty Schema" } }, { "location": { "type": "RESPONSE", "method": "GET", "statusCode": "200" }, "properties": { "description": "200 response" } } ] }, "servers": [ { "url": "/" } ], "components": { "schemas": { "Empty": { "type": "object", "title": "Empty Schema" } } } }
OpenAPI 2.0
PUT /restapis/<restapi_id>/documentation/parts&mode=overwrite&failonwarnings=true Host: apigateway.region.amazonaws.com Content-Type: application/json X-Amz-Date: YYYYMMDDTttttttZ Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret { "swagger": "2.0", "info": { "description": "description", "version": "1", "title": "doc" }, "host": "", "basePath": "/", "schemes": [ "https" ], "paths": { "/": { "get": { "description": "Method description.", "produces": [ "application/json" ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } } } } } }, "definitions": { "Empty": { "type": "object", "title": "Empty Schema" } }, "x-amazon-apigateway-documentation": { "version": "1.0.3", "documentationParts": [ { "location": { "type": "API" }, "properties": { "description": "API description", "info": { "description": "API info description 4", "version": "API info version 3" } } }, { "location": { "type": "METHOD", "method": "GET" }, "properties": { "description": "Method description." } }, { "location": { "type": "MODEL", "name": "Empty" }, "properties": { "title": "Empty Schema" } }, { "location": { "type": "RESPONSE", "method": "GET", "statusCode": "200" }, "properties": { "description": "200 response" } } ] } }

如果成功,此请求将返回一个 200 OK 响应,并在其负载中包含导入的 DocumentationPartId

{ "ids": [ "kg3mth", "796rtf", "zhek4p", "5ukm9s" ] }

另外,您也可以调用 restapi:importrestapi:put,并在 x-amazon-apigateway-documentation 对象中提供文档部分,作为 API 定义的输入 OpenAPI 文件的一部分。要从 API 导入中排除文档部分,请在请求查询参数中设置 ignore=documentation

使用 API Gateway 控制台导入文档部分

以下说明介绍了如何导入文档部分。

使用控制台从外部文件导入 API 文档部分的步骤

  1. 在控制台的主导航窗格中,为 API 选择文档

  2. 文档窗格中选择 Import Documentation (导入文档)

  3. 选择 Select OpenAPI File (选择 OpenAPI 文件) 以从驱动器加载文件,或者将文件内容复制并粘贴到文件视图中。有关示例,请参阅使用 API Gateway REST API 导入文档部分中示例请求的负载。

  4. (可选)选择 Fail on warnings (失败警告)Ignore warnings (忽略警告),然后从 Import mode (导入模式) 中选择 MergeOverwrite

  5. 选择 Import