# API Gateway에서 OpenAPI를 사용하여 REST API 개발
API Gateway를 사용하여 외부 정의 파일에서 API Gateway로 REST API를 가져올 수 있습니다. 현재 API Gateway는 [Amazon API Gateway의 REST API 중요 정보](api-gateway-known-issues.md#api-gateway-known-issues-rest-apis)에 나열된 파일을 제외하고 [OpenAPI v2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) 및 [OpenAPI v3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md) 정의 파일을 지원합니다. 새 정의로 덮어쓰기를 해서API를 업데이트하거나, 정의를 기존 API에 병합할 수 있습니다. 요청 URL에서 `mode` 쿼리 파라미터를 사용하여 옵션을 지정합니다.
API Gateway 콘솔에서 API 가져오기 기능을 사용하려면 [자습서: 예제를 가져와 REST API 생성](api-gateway-create-api-from-example.md)을 참조하세요.
**Topics**
+ [엣지 최적화된 API를 API Gateway로 가져오기](import-edge-optimized-api.md)
+ [리전 API를 API Gateway로 가져오기](import-export-api-endpoints.md)
+ [OpenAPI 파일을 가져와 기존 API 정의 업데이트](api-gateway-import-api-update.md)
+ [OpenAPI `basePath` 속성 설정](api-gateway-import-api-basePath.md)
+ [AWSOpenAPI 가져오기를 위한 변수](import-api-aws-variables.md)
+ [API를 API Gateway로 가져올 때 발생하는 오류 및 경고](api-gateway-import-api-errors-warnings.md)
+ [API Gateway에서 REST API 내보내기](api-gateway-export-api.md)
# 엣지 최적화된 API를 API Gateway로 가져오기
API OpenAPI 정의 파일을 가져와 `EDGE` 엔드포인트 유형을 OpenAPI 파일 외에 추가 입력으로 가져오기 작업에 지정함으로써 새로운 엣지 최적화 API를 생성할 수 있습니다. API Gateway 콘솔, AWS CLI 또는 AWS SDK를 사용하여 이를 수행할 수 있습니다.
API Gateway 콘솔에서 API 가져오기 기능을 사용하려면 [자습서: 예제를 가져와 REST API 생성](api-gateway-create-api-from-example.md)을 참조하세요.
**Topics**
+ [API Gateway 콘솔을 사용하여 엣지 최적화 API 가져오기](#import-edge-optimized-api-with-console)
+ [AWS CLI를 사용해 엣지 최적화 API 가져오기](#import-edge-optimized-api-with-awscli)
## API Gateway 콘솔을 사용하여 엣지 최적화 API 가져오기
API Gateway 콘솔을 사용해 엣지 최적화 API 가져오려면 다음을 따릅니다.
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. **API 생성**을 선택합니다.
1. **REST API** 아래에서 **가져오기**를 선택합니다.
1. API의 OpenAPI 정의를 복사하여 코드 편집기에 붙여넣거나 **파일 선택**을 선택하여 로컬 드라이브로부터 OpenAPI 파일을 로드합니다.
1. **API 엔드포인트 유형**에서 **엣지 최적화**를 선택합니다.
1. OpenAPI 정의를 가져오려면 **API 생성**을 선택합니다.
## AWS CLI를 사용해 엣지 최적화 API 가져오기
다음 [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html) 명령은 OpenAPI 정의 파일에서 API를 가져와 새로운 엣지 최적화 API를 생성합니다.
```
aws apigateway import-rest-api \
--fail-on-warnings \
--body 'file://path/to/API_OpenAPI_template.json'
```
또는 다음과 같이 `endpointConfigurationTypes`에 대한 `EDGE` 쿼리 문자열 파라미터의 명시적인 사양을 사용합니다.
```
aws apigateway import-rest-api \
--parameters endpointConfigurationTypes=EDGE \
--fail-on-warnings \
--body 'file://path/to/API_OpenAPI_template.json'
```
# 리전 API를 API Gateway로 가져오기
API를 가져올 때 API에 대해 리전 엔드포인트 구성을 선택할 수 있습니다. API Gateway 콘솔, AWS CLI 또는 AWS SDK를 사용할 수 있습니다.
API를 내보낼 때 내보낸 API 정의에 API 엔드포인트 구성은 포함되지 않습니다.
API Gateway 콘솔에서 API 가져오기 기능을 사용하려면 [자습서: 예제를 가져와 REST API 생성](api-gateway-create-api-from-example.md)을 참조하세요.
**Topics**
+ [API Gateway 콘솔을 사용하여 리전 API 가져오기](#import-regional-api-with-console)
+ [AWS CLI를 사용하여 리전 API 가져오기](#import-regional-api-with-awscli)
## API Gateway 콘솔을 사용하여 리전 API 가져오기
API Gateway 콘솔을 사용하여 리전 엔드포인트의 API를 가져오려면 다음과 같이 합니다.
1. [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)에서 API Gateway 콘솔에 로그인합니다.
1. **API 생성**을 선택합니다.
1. **REST API** 아래에서 **가져오기**를 선택합니다.
1. API의 OpenAPI 정의를 복사하여 코드 편집기에 붙여넣거나 **파일 선택**을 선택하여 로컬 드라이브로부터 OpenAPI 파일을 로드합니다.
1. **API 엔드포인트 유형**에서 **지역**을 선택합니다.
1. OpenAPI 정의를 가져오려면 **API 생성**을 선택합니다.
## AWS CLI를 사용하여 리전 API 가져오기
다음 [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html) 명령은 OpenAPI 정의 파일을 가져오고 엔드포인트 유형을 리전으로 설정합니다.
```
aws apigateway import-rest-api \
--parameters endpointConfigurationTypes=REGIONAL \
--fail-on-warnings \
--body 'file://path/to/API_OpenAPI_template.json'
```
# OpenAPI 파일을 가져와 기존 API 정의 업데이트
단계와 단계 변수 또는 API 키에 대한 참조뿐 아니라 엔드포인트 구성을 변경하지 않은 상태에서 기존 API를 업데이트만할 목적으로 API 정의를 가져올 수 있습니다.
가져와 업데이트하는 작업은 병합 또는 덮어쓰기의 두 가지 모드에서 발생할 수 있습니다.
API(`A`)를 다른 API(`B`)로 병합할 때 두 API가 충돌하는 정의를 공유하지 않으면 그 결과로 얻는 API는 `A`와 `B`의 정의를 모두 유지합니다. 충돌이 발생하는 경우 병합하는 API(`A`)의 메서드 정의가 병합되는 API(`B`)의 해당하는 메서드 정의를 재정의합니다. 예를 들어 `B`가 다음 메서드를 선언하여 `200` 및 `206` 응답을 반환했다고 가정하겠습니다.
```
GET /a
POST /a
```
그리고 `A`는 다음 메서드를 선언하여 `200` 및 `400` 응답을 반환합니다.
```
GET /a
```
`A`를 `B`에 병합하면 그 결과로 얻는 API는 다음 메서드를 출력합니다.
```
GET /a
```
`200` 및 `400` 응답을 반환하고
```
POST /a
```
`200` 및 `206` 응답을 반환합니다.
외부 API 정의를 여러 개의 더 작은 파트로 분해하고 한 번에 한 파트의 변경사항만 적용할 경우 API 병합이 유용합니다. 예를 들어, 여러 팀이 API의 서로 다른 파트를 담당하고 있고 다른 비율로 변경사항을 사용할 수 있는 경우 병합이 발생할 수 있습니다. 이 모드에서는 가져온 정의에 특별히 정의되지 않은 기존 API의 항목이 그대로 유지됩니다.
API(`A`)가 다른 API(`B`)를 덮어쓰면 그 결과로 얻는 API는 덮어쓴 API(`A`)의 정의를 취합니다. API 덮어쓰기는 외부 API 정의에 API의 전체 정의가 포함된 경우 유용합니다. 이 모드에서는 가져온 정의에 특별히 정의되지 않은 기존 API의 항목이 삭제됩니다.
API를 병합하려면 `PUT`에 `https://apigateway..amazonaws.com/restapis/?mode=merge` 요청을 제출하세요. `restapi_id` 경로 파라미터 값이 제공된 API 정의가 병합되는 API를 지정합니다.
다음 코드 조각에서는 JSON의 OpenAPI API 정의를 페이로드로 API Gateway의 이미 지정된 API와 병합하는 `PUT` 요청 예를 보여줍니다.
```
PUT /restapis/?mode=merge
Host:apigateway..amazonaws.com
Content-Type: application/json
Content-Length: ...
An OpenAPI API definition in JSON
```
병합 업데이트 작업에서는 2개의 전체 API 정의를 가져와서 함께 병합합니다. 소규모 증분 변경사항의 경우 [리소스 업데이트](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html) 작업을 사용할 수 있습니다.
API를 덮어쓰려면 `PUT` 요청을 `https://apigateway..amazonaws.com/restapis/?mode=overwrite`에 제출하세요. `restapi_id` 경로 파라미터는 제공된 API 정의로 덮어쓰는 API를 지정합니다.
다음 코드 조각에서는 JSON 형식의 OpenAPI 정의의 페이로드가 포함된 덮어쓰기 요청의 예를 보여줍니다.
```
PUT /restapis/?mode=overwrite
Host:apigateway..amazonaws.com
Content-Type: application/json
Content-Length: ...
An OpenAPI API definition in JSON
```
`mode` 쿼리 파라미터가 지정되지 않은 경우 병합이 사용됩니다.
**참고**
`PUT` 작업은 idempotent 방식이지만 원자성 작업은 아닙니다. 즉, 처리 과정에서 시스템 오류가 발생하면 API의 상태가 좋지 않을 수 있습니다. 그러나 작업을 성공적으로 반복하면 API가 첫 번째 작업이 성공한 것과 동일한 최종 상태가 됩니다.
# OpenAPI `basePath` 속성 설정
[OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md)에서 `basePath` 속성을 사용하여 `paths` 속성에 정의된 각 경로 앞에 하나 이상의 경로 파트를 제공할 수 있습니다. API Gateway에 리소스 경로를 표시할 여러 방법이 있기 때문에 Import API 기능은 가져오기 과정에서 `basePath` 속성을 해석하기 위한 옵션(무시, 앞에 추가, 분할)을 제공합니다.
[https://swagger.io/docs/specification/api-host-and-base-path/](https://swagger.io/docs/specification/api-host-and-base-path/)에서, `basePath`는 더 이상 상위 수준 속성이 아닙니다. 대신 API Gateway는 [서버 변수](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#serverVariableObject)를 규칙으로 사용합니다. Import API 기능은 가져오기 중에 기본 경로를 해석하기 위한 동일한 옵션을 제공합니다. 기본 경로는 다음과 같이 식별됩니다.
+ API에 `basePath` 변수가 없을 경우 Import API 기능은 `server.url` 문자열을 확인하여 `"/"` 위의 경로를 포함하는지 확인합니다. 포함할 경우 이 경로가 기본 경로로 사용됩니다.
+ API에 `basePath` 변수가 한 개만 있을 경우 Import API 기능은 `server.url`에 참조되지 않았더라도 이 변수를 기본 경로로 사용합니다.
+ API에 `basePath` 변수가 여러 개 있을 경우 Import API 기능은 첫 번째 변수만 기본 경로로 사용합니다.
## Ignore
OpenAPI 파일에서 `basePath` 값이 `/a/b/c`이고, `paths` 속성에 `/e` 및 `/f`가 포함된 경우 다음 `POST` 또는 `PUT` 요청은
```
POST /restapis?mode=import&basepath=ignore
```
```
PUT /restapis/api_id?basepath=ignore
```
API에 다음 리소스를 생성합니다.
+ `/`
+ `/e`
+ `/f`
그 결과 `basePath`는 존재하지 않는 것처럼 처리되고, 선언된 모든 API 리소스가 호스트를 기준으로 제공됩니다. 예를 들어, 프로덕션 단계를 참조하는 *Base Path* 및 *Stage* 값을 포함하지 않는 API 매핑이 포함된 사용자 지정 도메인 이름이 있는 경우 이 옵션을 사용할 수 있습니다.
**참고**
API Gateway는 정의 파일에 명시적으로 선언되지 않은 경우에도 자동으로 루트 리소스를 생성합니다.
지정하지 않을 경우 `basePath`는 기본적으로 `ignore`를 사용합니다.
## Prepend
OpenAPI 파일에서 `basePath` 값이 `/a/b/c`이고, `paths` 속성에 `/e` 및 `/f`가 포함된 경우 다음 `POST` 또는 `PUT` 요청은
```
POST /restapis?mode=import&basepath=prepend
```
```
PUT /restapis/api_id?basepath=prepend
```
API에 다음 리소스를 생성합니다.
+ `/`
+ `/a`
+ `/a/b`
+ `/a/b/c`
+ `/a/b/c/e`
+ `/a/b/c/f`
그 결과 `basePath`는 (메서드 없는) 추가 리소스 지정으로 처리되고 이 리소스를 선언된 리소스 세트에 추가합니다. 예를 들어, 다른 팀이 API의 다른 파트를 담당하고 있고 `basePath`가 각 팀의 API 파트에 대한 경로 위치를 참조할 수 있는 경우 이 옵션을 사용할 수 있습니다.
**참고**
API Gateway는 정의에 명시적으로 선언되지 않은 경우에도 자동으로 중간 리소스를 생성합니다.
## 분할
OpenAPI 파일에서 `basePath` 값이 `/a/b/c`이고, `paths` 속성에 `/e` 및 `/f`가 포함된 경우 다음 `POST` 또는 `PUT` 요청은
```
POST /restapis?mode=import&basepath=split
```
```
PUT /restapis/api_id?basepath=split
```
API에 다음 리소스를 생성합니다.
+ `/`
+ `/b`
+ `/b/c`
+ `/b/c/e`
+ `/b/c/f`
그 결과 가장 위의 경로 파트 `/a`를 리소스 경로의 시작으로 처리하고 API내에 추가 리소스(메서드 없음)를 생성합니다. 예를 들어, `a`가 API 일부로 공개할 단계 이름인 경우 이 옵션을 사용할 수 있습니다.
# AWSOpenAPI 가져오기를 위한 변수
OpenAPI 정의에서 다음 AWS 변수를 사용할 수 있습니다. API Gateway는 API를 가져올 때 변수를 확인합니다. 변수를 지정하려면 `${variable-name}`을 사용합니다. 다음 표에서는 사용 가능한 AWS 변수를 설명합니다.
| 변수 이름 | 설명 |
| --- | --- |
| AWS::AccountId | API를 가져오는 AWS 계정 ID입니다. 예: 123456789012. |
| AWS::Partition | API를 가져올 AWS 파티션입니다. 표준 AWS 리전에서 파티션은 aws입니다. |
| AWS::Region | API를 가져오는 AWS 리전입니다. 예: us-east-2. |
## AWS 변수 예제
다음 예제에서는 AWS 변수를 사용하여 통합에 대한 AWS Lambda 함수를 지정합니다.
------
#### [ OpenAPI 3.0 ]
```
openapi: "3.0.1"
info:
title: "tasks-api"
version: "v1.0"
paths:
/:
get:
summary: List tasks
description: Returns a list of tasks
responses:
200:
description: "OK"
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Task"
500:
description: "Internal Server Error"
content: {}
x-amazon-apigateway-integration:
uri:
arn:${AWS::Partition}:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:LambdaFunctionName/invocations
responses:
default:
statusCode: "200"
passthroughBehavior: "when_no_match"
httpMethod: "POST"
contentHandling: "CONVERT_TO_TEXT"
type: "aws_proxy"
components:
schemas:
Task:
type: object
properties:
id:
type: integer
name:
type: string
description:
type: string
```
------
# API를 API Gateway로 가져올 때 발생하는 오류 및 경고
외부 정의 파일을 API Gateway로 가져오면 API Gateway에서 경고 및 오류가 발생할 수 있습니다. 다음 섹션에서는 가져오기 중에 발생할 수 있는 오류 및 경고를 설명합니다.
## 가져오기 중 오류 발생
가져오기 중에 잘못된 OpenAPI 문서 같은 주요 문제에 대한 오류가 생성될 수 있습니다. 오류가 실패한 응답에서 예외(예: `BadRequestException`)로 반환됩니다. 오류가 발생하면 새 API 정의가 삭제되고 기존 API가 변경되지 않습니다.
## 가져오기 중 경고 발생
가져오는 동안 누락된 모델 참조와 같은 사소한 문제에 대한 경고가 생성될 수 있습니다. 경고가 발생한 경우 `failonwarnings=false` 쿼리 표현식이 요청 URL에 추가되면 작업이 계속됩니다. 그렇지 않으면 업데이트가 롤백됩니다. 기본적으로 `failonwarnings`는 `false`로 설정됩니다. 이 경우 경고가 결과 [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) 리소스에서 필드로 반환됩니다. 그렇지 않으면 경고가 예외의 메시지로 반환됩니다.
# API Gateway에서 REST API 내보내기
API Gateway 콘솔을 사용하거나 달리 API Gateway에서 REST API를 생성 및 구성한 경우, Amazon API Gateway Control Service의 일부인 API Gateway API 내보내기를 사용하여 이를 OpenAPI 파일로 내보낼 수 있습니다. API Gateway 내보내기 API를 사용하려면 API 요청에 서명해야 합니다. 요청 서명에 대한 자세한 내용은 **IAM 사용 설명서의 [AWS API 요청에 서명](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html)을 참조하세요. [Postman](https://www.postman.com) 확장뿐만 아니라 API Gateway 통합 확장도 내보낸 OpenAPI 정의 파일에 포함시킬 수 있습니다.
**참고**
AWS CLI를 사용하여 API를 내보낼 경우 다음 예와 같이 확장 파라미터를 포함시켜서 `x-amazon-apigateway-request-validator` 확장이 포함되도록 하세요.
```
aws apigateway get-export --parameters extensions='apigateway' --rest-api-id abcdefg123 --stage-name dev --export-type swagger latestswagger2.json
```
페이로드가 `application/json` 유형이 아닐 경우 API를 내보낼 수 없습니다. 내보내기를 시도하면 JSON 본문 모델이 없다는 오류 응답을 받게 됩니다.
## REST API 내보내기 요청
내보내기 API를 사용하여 GET 요청을 제출하고 내보낼 API를 URL 경로의 일부로 지정하여 기존 REST API를 내보내세요. 요청 URL의 형식은 다음과 같습니다.
------
#### [ OpenAPI 3.0 ]
```
https:///restapis//stages//exports/oas30
```
------
#### [ OpenAPI 2.0 ]
```
https:///restapis//stages//exports/swagger
```
------
API Gateway 확장(`integration` 값 사용) 또는 Postman 확장을 포함할지(`postman` 값 사용) 지정하는 `extensions` 쿼리 문자열을 추가할 수 있습니다.
그리고 `Accept` 헤더를 `application/json` 또는 `application/yaml`로 설정하여 API 정의 출력을 각각 JSON 또는 YAML 형식으로 받을 수 있습니다.
API Gateway 내보내기 API를 사용하여 GET 요청을 제출하는 자세한 내용은 [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html)를 참조하세요.
**참고**
API에서 모델을 정의한 경우 API Gateway가 모델을 내보내려면 "application/json" 콘텐츠 유형이어야 합니다. 그렇지 않으면 API Gateway에서 "Only found non-JSON body models for ..." 오류 메시지와 함께 예외가 발생합니다.
모델은 속성을 포함하거나 특정 JSONSchema 형식으로 정의해야 합니다.
## REST API OpenAPI 정의를 JSON으로 다운로드
OpenAPI 정의의 REST API를 JSON 형식으로 내보내고 다운로드하려면
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30
Host: apigateway..amazonaws.com
Accept: application/json
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger
Host: apigateway..amazonaws.com
Accept: application/json
```
------
예를 들어, 여기서 ``은 `us-east-1`일 수 있습니다. API Gateway를 사용할 수 있는 전체 리전은 [리전 및 엔드포인트](https://docs.aws.amazon.com/general/latest/gr/rande.html#apigateway_region)를 참조하세요.
## REST API OpenAPI 정의를 YAML로 다운로드
OpenAPI 정의의 REST API를 YAML 형식으로 내보내고 다운로드하려면
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
## Postman 확장이 포함된 REST API OpenAPI 정의를 JSON으로 다운로드
OpenAPI 정의의 REST API를 Postman을 사용해 JSON 형식으로 내보내고 다운로드하려면
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30?extensions=postman
Host: apigateway..amazonaws.com
Accept: application/json
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger?extensions=postman
Host: apigateway..amazonaws.com
Accept: application/json
```
------
## API Gateway 통합이 포함된 REST API OpenAPI 정의를 YAML로 다운로드
OpenAPI 정의의 REST API를 API Gateway 통합을 사용해 YAML 형식으로 내보내고 다운로드하려면
------
#### [ OpenAPI 3.0 ]
```
GET /restapis//stages//exports/oas30?extensions=integrations
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
#### [ OpenAPI 2.0 ]
```
GET /restapis//stages//exports/swagger?extensions=integrations
Host: apigateway..amazonaws.com
Accept: application/yaml
```
------
## API Gateway 콘솔을 사용하여 REST API 내보내기
[REST API를 단계로 배포](set-up-deployments.md#create-deployment)한 후 API Gateway 콘솔을 사용하여 단계의 API를 OpenAPI 파일로 계속 내보낼 수 있습니다.
API Gateway 콘솔의 **스테이지** 창에서 **스테이지 작업**, **내보내기**를 선택합니다.
![\[API Gateway 콘솔을 사용하여 REST API 내보내기\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/export-new-console.png)
**API 사양 유형**, **형식** 및 **확장**을 지정하여 API의 OpenAPI 정의를 다운로드합니다.