# 导入 API 文档
与导入 API 实体定义一样，您可以在 API Gateway 中将文档部分从外部 OpenAPI 文件导入到 API 中。您需要在有效的 OpenAPI 定义文件中指定 [x-amazon-apigateway-documentation 对象](api-gateway-swagger-extensions-documentation.md) 扩展中待导入的文档部分。导入文档的过程不会更改现有的 API 实体定义。
您可以选择在 API Gateway 中将新指定的文档部分合并到现有的文档部分中，也可以覆盖现有的文档部分。在 `MERGE` 模式下，在 OpenAPI 文件中定义的新文档部分会添加到 API 的 `DocumentationParts` 集合中。如果存在已导入的 `DocumentationPart`，在两者属性不同的情况下，导入的属性将替代现有属性。其他现有的文档属性不受影响。在 `OVERWRITE` 模式中，整个 `DocumentationParts` 集合将被替代，具体取决于导入的 OpenAPI 定义文件。
## 使用 API Gateway REST API 导入文档部分
要使用 API Gateway REST API 导入 API 文档，请调用 [documentationpart:import](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportDocumentationParts.html) 操作。以下示例显示了如何使用单个 `GET / ` 方法覆盖 API 的现有文档部分，并在成功后返回 `200 OK` 响应。
------
#### [ OpenAPI 3.0 ]
```
PUT /restapis//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//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](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportRestApi.html) 或 [restapi:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutRestApi.html)，并在 `x-amazon-apigateway-documentation` 对象中提供文档部分，作为 API 定义的输入 OpenAPI 文件的一部分。要从 API 导入中排除文档部分，请在请求查询参数中设置 `ignore=documentation`。
## 使用 API Gateway 控制台导入文档部分
以下说明介绍了如何导入文档部分。
**使用控制台从外部文件导入 API 文档部分的步骤**
1. 在主导航窗格中，选择**文档**。
1. 选择**导入**。
1. 如果您已有文档，请选择**覆盖**或**合并**新文档。
1. 选择**选择文件**以从驱动器加载文件，或将文件内容输入到文件视图中。有关示例，请参阅[使用 API Gateway REST API 导入文档部分](#api-gateway-importing-api-with-swagger-file-using-rest-api)中示例请求的负载。
1. 选择如何处理导入时的警告。选择**警告时失败**或**忽略警告**。有关更多信息，请参阅 [将 API 导入 API Gateway 时出现的错误和警告](api-gateway-import-api-errors-warnings.md)。
1. 选择**导入**。