HTTP API の OpenAPI 定義の使用

HTTP API は、OpenAPI 3.0 定義ファイルを使用して定義できます。次に、定義を API Gateway にインポートして API を作成できます。OpenAPI への API Gateway 拡張の詳細については、「OpenAPI への API Gateway 拡張機能の使用」を参照してください。

HTTP API のインポート

HTTP API は、OpenAPI 3.0 定義ファイルをインポートすることによって作成できます。

REST API から HTTP API に移行するには、REST API を OpenAPI 3.0 定義ファイルとしてエクスポートできます。次に、API 定義を HTTP API としてインポートします。REST API のエクスポートの詳細については、「API Gateway から REST API をエクスポートする」を参照してください。

注記

HTTP API は、REST API と同じ AWS 変数をサポートします。詳細については、「OpenAPI インポート用の AWS 変数」を参照してください。

検証情報のインポート

API のインポート時に、API Gateway から 3 つのカテゴリの検証情報が提供されます。

Info

プロパティは OpenAPI 仕様では有効ですが、そのプロパティは HTTP API ではサポートされていません。

たとえば、次の OpenAPI 3.0 スニペットは、HTTP API がリクエストの検証をサポートしていないため、インポート時に情報を生成します。API Gateway は、requestBody フィールドと schema フィールドを無視します。

"paths": {
  "/": {
    "get": {
      "x-amazon-apigateway-integration": {
        "type": "AWS_PROXY",
        "httpMethod": "POST",
        "uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
        "payloadFormatVersion": "1.0"
      },
      "requestBody": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Body"
            }
          }
        }
      }
    }
  }
  ...
},
"components": {
  "schemas": {
    "Body": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string"
        }
      }
    }
    ...
  }
  ...
}

警告

プロパティまたは構造は、OpenAPI 仕様では無効ですが、API の作成をブロックしません。API Gateway でこれらの警告を無視して API の作成を続行するか、警告時に API の作成を停止するかを指定できます。

次の OpenAPI 3.0 ドキュメントでは、HTTP API は Lambda プロキシと HTTP プロキシの統合のみをサポートしているため、インポート時に警告が生成されます。

"x-amazon-apigateway-integration": {
  "type": "AWS",
  "httpMethod": "POST",
  "uri": "arn:aws:lambda:us-east-2:123456789012:function:HelloWorld",
  "payloadFormatVersion": "1.0"
}

エラー

OpenAPI 仕様が無効であるか、形式が正しくありません。API Gateway は、不正な形式のドキュメントからリソースを作成できません。エラーを修正してから、もう一度やり直してください。

次の API 定義では、HTTP API は OpenAPI 3.0 仕様のみをサポートしているため、インポート時にエラーが発生します。

{
  "swagger": "2.0.0",
  "info": {
    "title": "My API",
    "description": "An Example OpenAPI definition for Errors/Warnings/ImportInfo",
    "version": "1.0"
  }
  ...
}

別の例として、OpenAPI では、ユーザーが特定のオペレーションに複数のセキュリティ要件を適用した API を定義できますが、API Gateway はこれをサポートしません。各オペレーションには、IAM 認証、Lambda オーソライザー 、または JWT オーソライザーのいずれかしか持つことができません。複数のセキュリティ要件をモデル化しようとすると、エラーが発生します。

AWS CLI を使用した API のインポート

次のコマンドは、OpenAPI 3.0 定義ファイル api-definition.json を HTTP API としてインポートします。

aws apigatewayv2 import-api --body file://api-definition.json

次のサンプル OpenAPI 3.0 定義をインポートして、HTTP API を作成することができます。

{
  "openapi": "3.0.1",
  "info": {
    "title": "Example Pet Store",
    "description": "A Pet Store API.",
    "version": "1.0"
  },
  "paths": {
    "/pets": {
      "get": {
        "operationId": "GET HTTP",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pets"
                }
              }
            }
          }
        },
        "x-amazon-apigateway-integration": {
          "type": "HTTP_PROXY",
          "httpMethod": "GET",
          "uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets",
          "payloadFormatVersion": 1.0
        }
      },
      "post": {
        "operationId": "Create Pet",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NewPet"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "200 response",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NewPetResponse"
                }
              }
            }
          }
        },
        "x-amazon-apigateway-integration": {
          "type": "HTTP_PROXY",
          "httpMethod": "POST",
          "uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets",
          "payloadFormatVersion": 1.0
        }
      }
    },
    "/pets/{petId}": {
      "get": {
        "operationId": "Get Pet",
        "parameters": [
          {
            "name": "petId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200 response",
            "headers": {
              "Access-Control-Allow-Origin": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pet"
                }
              }
            }
          }
        },        
        "x-amazon-apigateway-integration": {
          "type": "HTTP_PROXY",
          "httpMethod": "GET",
          "uri": "http://petstore.execute-api.us-west-1.amazonaws.com/petstore/pets/{petId}",
          "payloadFormatVersion": 1.0
        }
      }
    }
  },
  "x-amazon-apigateway-cors": {
    "allowOrigins": [
      "*"
    ],
    "allowMethods": [
      "GET",
      "OPTIONS",
      "POST"
    ],
    "allowHeaders": [
      "x-amzm-header",
      "x-apigateway-header",
      "x-api-key",
      "authorization",
      "x-amz-date",
      "content-type"
    ]
  },
  "components": {
    "schemas": {
      "Pets": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/Pet"
        }
      },
      "Empty": {
        "type": "object"
      },
      "NewPetResponse": {
        "type": "object",
        "properties": {
          "pet": {
            "$ref": "#/components/schemas/Pet"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "Pet": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "price": {
            "type": "number"
          }
        }
      },
      "NewPet": {
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/PetType"
          },
          "price": {
            "type": "number"
          }
        }
      },
      "PetType": {
        "type": "string",
        "enum": [
          "dog",
          "cat",
          "fish",
          "bird",
          "gecko"
        ]
      }
    }
  }
}