# API 설명서 가져오기
API 엔터티 정의 가져오기와 마찬가지로 외부 OpenAPI 파일에서 API Gateway의 API로 설명서 부분을 가져올 수 있습니다. 유효한 OpenAPI 정의 파일의 [x-amazon-apigateway-documentation 객체](api-gateway-swagger-extensions-documentation.md) 확장 내에서 가져올 설명서 부분을 지정합니다. 설명서를 가져와도 기존 API 엔터티 정의는 변경되지 않습니다.
새로 지정된 설명서 부분을 API Gateway의 기존 설명서 부분에 병합하거나 기존 설명서 부분을 덮어쓸 수 있습니다. `MERGE` 모드에서는 OpenAPI 파일에 정의된 새 설명서 부분이 API의 `DocumentationParts` 컬렉션에 추가됩니다. 가져온 `DocumentationPart`가 이미 있는 경우 두 개의 속성이 다르면 가져온 속성이 기존 속성을 대체합니다. 다른 기존 설명서 속성은 그대로 남아 있습니다. `OVERWRITE` 모드에서는 전체 `DocumentationParts` 컬렉션이 가져온 OpenAPI 정의 파일에 따라 대체됩니다.
## API Gateway REST API를 사용하여 설명서 부분 가져오기
API Gateway REST API를 사용하여 API 설명서를 가져오려면 [documentationpart:import](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportDocumentationParts.html) 작업을 호출합니다. 다음 예에서는 API의 기존 설명서 부분을 단일 `GET / ` 메서드로 덮어쓰고 성공하면 `200 OK` 응답을 반환하는 방법을 보여줍니다.
------
#### [ OpenAPI 3.0 ]
```
PUT /restapis//documentation/parts&mode=overwrite&failonwarnings=true
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"openapi": "3.0.0",
"info": {
"description": "description",
"version": "1",
"title": "doc"
},
"paths": {
"/": {
"get": {
"description": "Method description.",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
}
}
}
},
"x-amazon-apigateway-documentation": {
"version": "1.0.3",
"documentationParts": [
{
"location": {
"type": "API"
},
"properties": {
"description": "API description",
"info": {
"description": "API info description 4",
"version": "API info version 3"
}
}
},
{
"location": {
"type": "METHOD",
"method": "GET"
},
"properties": {
"description": "Method description."
}
},
{
"location": {
"type": "MODEL",
"name": "Empty"
},
"properties": {
"title": "Empty Schema"
}
},
{
"location": {
"type": "RESPONSE",
"method": "GET",
"statusCode": "200"
},
"properties": {
"description": "200 response"
}
}
]
},
"servers": [
{
"url": "/"
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
PUT /restapis//documentation/parts&mode=overwrite&failonwarnings=true
Host: apigateway.region.amazonaws.com
Content-Type: application/json
X-Amz-Date: YYYYMMDDTttttttZ
Authorization: AWS4-HMAC-SHA256 Credential=access_key_id/YYYYMMDD/region/apigateway/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=sigv4_secret
{
"swagger": "2.0",
"info": {
"description": "description",
"version": "1",
"title": "doc"
},
"host": "",
"basePath": "/",
"schemes": [
"https"
],
"paths": {
"/": {
"get": {
"description": "Method description.",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
}
}
}
},
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
},
"x-amazon-apigateway-documentation": {
"version": "1.0.3",
"documentationParts": [
{
"location": {
"type": "API"
},
"properties": {
"description": "API description",
"info": {
"description": "API info description 4",
"version": "API info version 3"
}
}
},
{
"location": {
"type": "METHOD",
"method": "GET"
},
"properties": {
"description": "Method description."
}
},
{
"location": {
"type": "MODEL",
"name": "Empty"
},
"properties": {
"title": "Empty Schema"
}
},
{
"location": {
"type": "RESPONSE",
"method": "GET",
"statusCode": "200"
},
"properties": {
"description": "200 response"
}
}
]
}
}
```
------
성공하면 이 요청은 페이로드에 가져온 `DocumentationPartId`를 포함하는 200 OK 응답을 반환합니다.
```
{
"ids": [
"kg3mth",
"796rtf",
"zhek4p",
"5ukm9s"
]
}
```
또한 [restapi:import](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportRestApi.html) 또는 [restapi:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutRestApi.html)을 호출하고 `x-amazon-apigateway-documentation` 객체의 설명서 부분을 API 정의의 입력 OpenAPI 파일의 부분으로 제공할 수도 있습니다. API 가져오기에서 설명서 부분을 제외하려면 요청 쿼리 파라미터에서 `ignore=documentation`을 설정하십시오.
## API Gateway 콘솔을 사용하여 문서 부분 가져오기
다음 지침에서는 설명서 부분을 가져오는 방법을 설명합니다.
**콘솔을 사용하여 외부 파일로부터 API의 설명서 부분 가져오는 방법**
1. 기본 탐색 창에서 **설명서**를 선택합니다.
1. **가져오기**를 선택합니다.
1. 기존 설명서가 있는 경우 새 문서에 대한 **덮어쓰기** 또는 **병합** 선택합니다.
1. **파일 선택**을 선택하여 드라이브로부터 파일을 로드하거나 파일 내용을 파일 보기에 입력합니다. 예를 들어, [API Gateway REST API를 사용하여 설명서 부분 가져오기](#api-gateway-importing-api-with-swagger-file-using-rest-api)에 포함된 예제 요청의 페이로드를 참조합니다.
1. 가져올 때 경고를 처리하는 방법을 선택합니다. **경고 실패** 또는 **경고 무시**를 선택합니다. 자세한 내용은 [API를 API Gateway로 가져올 때 발생하는 오류 및 경고](api-gateway-import-api-errors-warnings.md) 섹션을 참조하세요.
1. **가져오기**를 선택합니다.