# 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` がすでに存在する場合、2 つの属性が異なる場合はインポートされた属性によって既存の属性が置き換えられます。他の既存のドキュメント属性は影響を受けません。`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) オペレーションを呼び出します。次の例は、API の既存のドキュメントパーツを単一の `GET / ` メソッドに置き換えて、成功時は `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"
}
}
]
}
}
```
------
成功すると、このリクエストはペイロードにインポートされた `DocumentationPartId` を含む 200 OK レスポンスを返します。
```
{
"ids": [
"kg3mth",
"796rtf",
"zhek4p",
"5ukm9s"
]
}
```
加えて、API 定義の入力 OpenAPI ファイルの一部として `x-amazon-apigateway-documentation` オブジェクトでドキュメントパートを指定して、[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) を呼び出すこともできます。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 Gateway への API のインポートによるエラーと警告](api-gateway-import-api-errors-warnings.md)」を参照してください。
1. [**インポート**] を選択します。