# API Gateway에서 HTTP API에 대한 OpenAPI 정의 사용
OpenAPI 3.0 정의 파일을 사용하여 HTTP API를 정의할 수 있습니다. 그런 다음 정의를 API Gateway로 가져와서 API를 생성할 수 있습니다. OpenAPI로 API Gateway 확장에 대한 자세한 내용은 [API Gateway용 OpenAPI 확장 프로그램](api-gateway-swagger-extensions.md) 단원을 참조하세요.
## 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 내보내기](api-gateway-export-api.md) 단원을 참조하세요.
**참고**
HTTP API는 REST API와 동일한 AWS 변수를 지원합니다. 자세한 내용은 [AWSOpenAPI 가져오기를 위한 변수](import-api-aws-variables.md) 단원을 참조하세요.
### 검증 정보 가져오기
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 가져오기
다음 [import-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/import-api.html) 명령은 OpenAPI 3.0 정의 파일 `api-definition.json`을 HTTP API로 가져옵니다.
**Example**
```
aws apigatewayv2 import-api --body file://api-definition.json
```
**Example**
다음 예제 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"
]
}
}
}
}
```
# API Gateway에서 HTTP API 내보내기
HTTP API를 생성한 후 API Gateway에서 API의 OpenAPI 3.0 정의를 내보낼 수 있습니다. 내보낼 스테이지를 선택하거나 API의 최신 구성을 내보낼 수 있습니다. 내보낸 API 정의를 API Gateway로 가져와 동일한 또 다른 API를 생성할 수도 있습니다. API 정의 가져오기에 대한 자세한 내용은 [HTTP API 가져오기](http-api-open-api.md#http-api-import) 단원을 참조하세요.
## AWS CLI를 사용하여 스테이지의 OpenAPI 3.0 정의 내보내기
다음 [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) 명령은 `prod`라는 API 스테이지의 OpenAPI 정의를 `stage-definition.yaml`이라는 YAML 파일로 내보냅니다. 내보낸 정의 파일에는 기본적으로 [API Gateway 확장](api-gateway-swagger-extensions.md)이 포함됩니다.
```
aws apigatewayv2 export-api \
--api-id api-id \
--output-type YAML \
--specification OAS30 \
--stage-name prod \
stage-definition.yaml
```
## AWS CLI를 사용하여 API의 최신 변경 사항에 대한 OpenAPI 3.0 정의 내보내기
다음 [export-api](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/export-api.html) 명령은 HTTP API의 OpenAPI 정의를 `latest-api-definition.json`이라는 JSON 파일로 내보냅니다. 이 명령은 스테이지를 지정하지 않으므로 API Gateway는 스테이지에 배포되었는지 여부에 관계없이 API의 최신 구성을 내보냅니다. 내보낸 정의 파일에는[API Gateway 확장](api-gateway-swagger-extensions.md)이 포함되지 않습니다.
```
aws apigatewayv2 export-api \
--api-id api-id \
--output-type JSON \
--specification OAS30 \
--no-include-extensions \
latest-api-definition.json
```
자세한 내용은 *Amazon API Gateway 버전 2 API 참조*의 [ExportAPI](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-exports-specification.html#apis-apiid-exports-specification-http-methods)를 참조하세요.
## API Gateway 콘솔을 사용하여 OpenAPI 3.0 정의 내보내기
다음 절차에서는 HTTP API의 OpenAPI 정의를 내보내는 방법을 보여줍니다.
**API Gateway 콘솔을 사용하여 OpenAPI 3.0 정의를 내보내려면**
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. HTTP API를 선택합니다.
1. 기본 탐색 창의 **개발**에서 **내보내기**를 선택합니다.
1. API 내보내기를 위한 다음과 같은 옵션을 선택합니다.
![\[HTTP API 내보내기 옵션.\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/export-http-api.png)
1. **소스**에서 OpenAPI 3.0 정의의 소스를 선택합니다. 내보낼 스테이지를 선택하거나 API의 최신 구성을 내보낼 수 있습니다.
1. [API Gateway 확장](api-gateway-swagger-extensions.md)을 포함하려면 **API Gateway 확장 포함**을 켭니다.
1. **출력 형식**에서 출력 형식을 선택합니다.
1. **다운로드**를 선택합니다.