使用 HTTP API 的 OpenAPI 定義

您可以使用 OpenAPI 3.0 定義檔來定義 HTTP API。之後，您就能將定義匯入 API Gateway，以建立 API。若要進一步了解 OpenAPI 的 API Gateway 延伸，請參閱使用 OpenAPI 的 API Gateway 延伸。

匯入 HTTP API

您可以透過匯入 OpenAPI 3.0 定義檔案來建立 HTTP API。

若要從 REST API 遷移至 HTTP API，您可以將 REST API 匯出為 OpenAPI 3.0 定義檔案。然後將 API 定義匯入為 HTTP API。若要進一步了解如何匯出 REST API，請參閱從 API Gateway 匯出 REST API。

注意

HTTP API 支援與其他 API 相同的 AWS 變數。如需進一步了解，請參閱AWS 匯入應用程式介面的變數。

匯入驗證資訊

匯入 API 時，API Gateway 會提供三種類別的驗證資訊。

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 授權方。嘗試建立多個安全性需求的模型會導致錯誤。

使用匯入 API AWS CLI

下列命令會將 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"
        ]
      }
    }
  }
}