本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 匯入 API 文件
如同匯入 API 實體定義，您可以將文件組件從外部 OpenAPI 檔案匯入 API Gateway 中的 API。您可以在有效 OpenAPI 定義檔的 [x-amazon-apigateway-documentation 物件](api-gateway-swagger-extensions-documentation.md) 延伸中，指定要匯入的文件組件。匯入文件不會改變現有的 API 實體定義。
您可以在 API Gateway 中選擇將新指定的文件組件合併到現有的文件組件，或覆寫現有的文件組件。在 `MERGE` 模式下，OpenAPI 檔案中定義的新文件組件會新增至 API 的 `DocumentationParts` 集合。如果匯入的 `DocumentationPart` 已存在，匯入的屬性會取代現有的屬性 (如果兩者不同)。其他現有的文件屬性則不受影響。在 `OVERWRITE` 模式下，會根據已匯入的 OpenAPI 定義檔來取代整個 `DocumentationParts` 集合。
## 使用 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. 選擇**匯入**。