导入 API 文档 - Amazon API Gateway
使用 API Gateway REST API 导入文档部分使用 API Gateway 控制台导入文档部分
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

导入 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.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:import 或 restapi:put，并在 x-amazon-apigateway-documentation 对象中提供文档部分，作为 API 定义的输入 OpenAPI 文件的一部分。要从 API 导入中排除文档部分，请在请求查询参数中设置 ignore=documentation。

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

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

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

  1. 在主导航窗格中，选择文档。

  2. 选择导入。

  3. 如果您已有文档，请选择覆盖或合并新文档。

  4. 选择选择文件以从驱动器加载文件，或将文件内容输入到文件视图中。有关示例，请参阅使用 API Gateway REST API 导入文档部分中示例请求的负载。

  5. 选择如何处理导入时的警告。选择警告时失败或忽略警告。有关更多信息，请参阅导入期间的错误和警告。

  6. 选择 Import。