API ドキュメントのインポート - Amazon API Gateway
API Gateway REST API を使用してドキュメントパートをインポートするAPI Gateway コンソールを使用してドキュメントパートをインポートする

API ドキュメントのインポート

API エンティティ定義のインポートと同様、ドキュメントパートは API Gateway で外部 OpenAPI ファイルから API にインポートできます。インポートするドキュメントパートは、有効な OpenAPI 定義ファイルの x-amazon-apigateway-documentation オブジェクト 拡張内で指定します。ドキュメントをインポートしても、既存の API エンティティ定義は変更されません。

API Gateway で新しく指定されたドキュメントパートを既存のドキュメントパートにマージしたり、既存のドキュメントパートを上書きしたりするオプションがあります。MERGE モードでは、OpenAPI ファイルで定義された新しいドキュメントパーツが API の DocumentationParts コレクションに追加されます。インポートする DocumentationPart がすでに存在する場合、2 つの属性が異なる場合はインポートされた属性によって既存の属性が置き換えられます。他の既存のドキュメント属性は影響を受けません。OVERWRITE モードでは、インポートされた OpenAPI 定義ファイルに従って DocumentationParts コレクション全体が置き換えられます。

API Gateway REST API を使用してドキュメントパートをインポートする

API Gateway REST API を使用して API ドキュメントをインポートするには、documentationpart:import オペレーションを呼び出します。次の例は、API の既存のドキュメントパーツを単一の GET / メソッドに置き換えて、成功時は 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"
        }
      }
    ]
  }
}

成功すると、このリクエストはペイロードにインポートされた DocumentationPartId を含む 200 OK レスポンスを返します。

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

加えて、API 定義の入力 OpenAPI ファイルの一部として x-amazon-apigateway-documentation オブジェクトでドキュメントパートを指定して、restapi:import または restapi:put を呼び出すこともできます。API インポートからドキュメントパーツを除外するには、リクエストクエリパラメータで ignore=documentation を設定します。

API Gateway コンソールを使用してドキュメントパートをインポートする

次の手順では、ドキュメントパーツをインポートする方法について説明します。

コンソールを使用して API のドキュメントパーツを外部ファイルからインポートするには

  1. メインナビゲーションペインで、[ドキュメント] を選択します。

  2. [Import] (インポート) を選択します。

  3. 既存のドキュメントがある場合は、新しいドキュメントを [上書き] するか [マージ] するかを選択します。

  4. [ファイルの選択] を選択してドライブからファイルをロードするか、ファイルのコンテンツをファイルビューに入力します。例として、「API Gateway REST API を使用してドキュメントパートをインポートする」にあるサンプルリクエストのペイロードを参照してください。

  5. インポート時の警告の処理方法を選択します。[警告を失敗とみなす] または [警告を無視する] を選択します。詳細については、「API Gateway への API のインポートによるエラーと警告」を参照してください。

  6. [Import] (インポート) を選択します。