API Gateway에서 HTTP API에 대한 OpenAPI 정의 사용

OpenAPI 3.0 정의 파일을 사용하여 HTTP API를 정의할 수 있습니다. 그런 다음 정의를 API Gateway로 가져와서 API를 생성할 수 있습니다. OpenAPI로 API Gateway 확장에 대한 자세한 내용은 API Gateway용 OpenAPI 확장 프로그램 단원을 참조하세요.

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는 REST API와 동일한 AWS 변수를 지원합니다. 자세한 내용은 AWSOpenAPI 가져오기를 위한 변수 단원을 참조하세요.

검증 정보 가져오기

API를 가져올 때 API Gateway는 세 가지 범주의 검증 정보를 제공합니다.

Info

속성은 OpenAPI 사양에 따라 유효하지만, HTTP API에 대해서는 해당 속성이 지원되지 않습니다.

예를 들어, HTTP API는 요청 검증을 지원하지 않으므로 다음 OpenAPI 3.0 코드 조각은 가져오기에 대한 정보를 생성합니다. 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 생성을 중지할지를 지정할 수 있습니다.

HTTP API는 Lambda 프록시 및 HTTP 프록시 통합만 지원하므로 다음과 같은 OpenAPI 3.0 문서에서는 가져오기에 대한 경고가 생성됩니다.

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

오류

OpenAPI 사양이 올바르지 않거나 형식이 잘못되었습니다. API Gateway는 잘못된 형식의 문서에서 리소스를 만들 수 없습니다. 오류를 수정한 다음, 다시 시도해야 합니다.

HTTP API는 OpenAPI 3.0 사양만 지원하므로 다음과 같은 API 정의는 가져올 때 오류가 발생합니다.

{
  "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"
        ]
      }
    }
  }
}