# API Gateway REST API를 사용하여 API 설명서 게시
API에 대한 설명서를 게시하려면 설명서 스냅샷을 생성 또는 업데이트하거나 가져온 다음, 설명서 스냅샷을 API 단계와 연결합니다. 설명서 스냅샷을 생성할 때 이를 동시에 API 단계와 연결할 수도 있습니다.
**Topics**
+ [설명서 스냅샷을 생성하여 API 단계와 연결](#api-gateway-documenting-api-publishing-create-documentation-version-with-stage)
+ [설명서 스냅샷 만들기](#api-gateway-documenting-api-publishing-create-documentation-version)
+ [설명서 스냅샷 업데이트](#api-gateway-documenting-api-publishing-update-documentation-version)
+ [설명서 스냅샷 가져오기](#api-gateway-documenting-api-publishing-get-documentation-version)
+ [설명서 스냅샷을 API 단계와 연결](#api-gateway-documenting-api-publishing-stage-association)
+ [단계와 연결된 설명서 스냅샷 다운로드](#api-gateway-documenting-api-publishing-export-documentation-version)
## 설명서 스냅샷을 생성하여 API 단계와 연결
API의 설명서 부분의 스냅샷을 생성하여 동시에 API 단계와 연결하려면 다음 `POST` 요청을 제출하십시오.
```
POST /restapis/restapi_id/documentation/versions HTTP/1.1
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
{
"documentationVersion" : "1.0.0",
"stageName": "prod",
"description" : "My API Documentation v1.0.0"
}
```
성공하면 해당 작업은 페이로드로 새로 생성된 `200 OK` 인스턴스를 포함하는 `DocumentationVersion` 응답을 반환합니다.
또는 API 단계와 먼저 연결하지 않고 설명서 스냅샷을 생성한 다음, [restapi:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateRestApi.html)를 호출하여 스냅샷을 지정된 API 단계와 연결할 수 있습니다. 기존 설명서 스냅샷을 업데이트 또는 쿼리한 다음, 단계 연결을 업데이트할 수도 있습니다. 다음 4개 단원에서 단계를 보여드립니다.
## 설명서 스냅샷 만들기
API 설명서 부분의 스냅샷을 생성하려면 새 [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) 리소스를 생성하여 API의 [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) 컬렉션에 추가합니다.
```
POST /restapis/restapi_id/documentation/versions HTTP/1.1
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
{
"documentationVersion" : "1.0.0",
"description" : "My API Documentation v1.0.0"
}
```
성공하면 해당 작업은 페이로드로 새로 생성된 `200 OK` 인스턴스를 포함하는 `DocumentationVersion` 응답을 반환합니다.
## 설명서 스냅샷 업데이트
해당 [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) 리소스의 `description` 속성을 수정하는 방법으로만 설명서 스냅샷을 업데이트할 수 있습니다. 다음 예에서는 `version` 버전 ID(예: `1.0.0`)로 식별된 설명서 스냅샷의 설명을 업데이트하는 방법을 보여줍니다.
```
PATCH /restapis/restapi_id/documentation/versions/version HTTP/1.1
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
{
"patchOperations": [{
"op": "replace",
"path": "/description",
"value": "My API for testing purposes."
}]
}
```
성공하면 해당 작업은 페이로드로 업데이트된 `200 OK` 인스턴스를 포함하는 `DocumentationVersion` 응답을 반환합니다.
## 설명서 스냅샷 가져오기
설명서 스냅샷을 가져오려면 지정된 [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) 리소스에 대해 `GET` 요청을 제출합니다. 다음 예에서는 지정된 버전 ID 1.0.0의 설명서 스냅샷을 가져오는 방법을 보여줍니다.
```
GET /restapis//documentation/versions/1.0.0 HTTP/1.1
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
```
## 설명서 스냅샷을 API 단계와 연결
API 설명서를 게시하려면 설명서 스냅샷을 API 단계와 연결합니다. 설명서 버전을 단계와 연결하기 전에 API 단계를 이미 생성해야 합니다.
[API Gateway REST API](https://docs.aws.amazon.com/apigateway/latest/api/)를 사용하여 설명서 스냅샷을 API 단계와 연결하려면 [stage:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateStage.html) 작업을 호출하여 `stage.documentationVersion` 속성에서 원하는 설명서 버전을 설정합니다.
```
PATCH /restapis/RESTAPI_ID/stages/STAGE_NAME
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
{
"patchOperations": [{
"op": "replace",
"path": "/documentationVersion",
"value": "VERSION_IDENTIFIER"
}]
}
```
## 단계와 연결된 설명서 스냅샷 다운로드
설명서 부분의 한 버전이 단계와 연결된 후, API Gateway 콘솔, API Gateway REST API, SDK 중 하나 또는 API Gateway용 AWS CLI를 사용하여 API 엔터티 정의와 함께 설명서 부분을 외부 파일로 내보낼 수 있습니다. 이 프로세스는 API를 내보내는 프로세스와 동일합니다. 내보낸 파일 형식은 JSON 또는 YAML일 수 있습니다.
또한 API Gateway REST API를 사용하여 API 설명서 부분, API 통합 및 권한 부여자를 API 내보내기에 포함하도록 `extension=documentation,integrations,authorizers` 쿼리 파라미터를 명시적으로 설정할 수도 있습니다. 기본적으로 API를 내보낼 때 설명서 부분은 포함되지만 통합 및 권한 부여자는 제외됩니다. API 내보내기의 기본 출력은 설명서 배포에 적합합니다.
API Gateway REST API를 사용하여 API 설명서를 외부 JSON OpenAPI 파일로 내보내려면 다음 `GET` 요청을 제출합니다.
```
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=documentation HTTP/1.1
Accept: application/json
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
```
여기서 `x-amazon-apigateway-documentation` 객체에는 설명서 부분이 포함되고 API 엔터티 정의에는 OpenAPI에서 지원하는 설명서 속성이 포함됩니다. 출력에는 통합 또는 Lambda 권한 부여자(이전에는 사용자 지정 권한 부여자라고 함)의 세부 정보가 포함되지 않습니다. 두 가지 세부 정보를 모두 포함하려면 `extensions=integrations,authorizers,documentation`을 설정하십시오. 통합 세부 정보는 포함하지만 권한 부여자 세부 정보는 포함하지 않으려면 `extensions=integrations,documentation`을 설정하십시오.
결과를 JSON 파일로 출력하려면 요청에 `Accept:application/json` 헤더를 설정해야 합니다. YAML 출력을 생성하려면 요청 헤더를 `Accept:application/yaml`로 변경하십시오.
예를 들어, 루트 리소스(`GET`)에서 간단한 `/` 메서드를 표시하는 API를 볼 수 있습니다. 이 API에는 OpenAPI 정의 파일에 정의된 API 엔터티가 네 개 있습니다. 각각 `API`, `MODEL`, `METHOD` 및 `RESPONSE` 유형에 해당하는 엔터티입니다. 설명서 부분이 각 `API`, `METHOD` 및 `RESPONSE` 엔터티에 추가되었습니다. 이전 설명서 내보내기 명령을 호출하면 설명서 부분이 `x-amazon-apigateway-documentation` 객체에 표준 OpenAPI 파일에 대한 확장으로 나열되는 다음과 같은 출력이 표시됩니다.
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"description": "API info description",
"version": "2016-11-22T22:39:14Z",
"title": "doc",
"x-bar": "API info x-bar"
},
"paths": {
"/": {
"get": {
"description": "Method description.",
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-example": "x- Method example"
},
"x-bar": "resource x-bar"
}
},
"x-amazon-apigateway-documentation": {
"version": "1.0.0",
"createdDate": "2016-11-22T22:41:40Z",
"documentationParts": [
{
"location": {
"type": "API"
},
"properties": {
"description": "API description",
"foo": "API foo",
"x-bar": "API x-bar",
"info": {
"description": "API info description",
"version": "API info version",
"foo": "API info foo",
"x-bar": "API info x-bar"
}
}
},
{
"location": {
"type": "METHOD",
"method": "GET"
},
"properties": {
"description": "Method description.",
"x-example": "x- Method example",
"foo": "Method foo",
"info": {
"version": "method info version",
"description": "method info description",
"foo": "method info foo"
}
}
},
{
"location": {
"type": "RESOURCE"
},
"properties": {
"description": "resource description",
"foo": "resource foo",
"x-bar": "resource x-bar",
"info": {
"description": "resource info description",
"version": "resource info version",
"foo": "resource info foo",
"x-bar": "resource info x-bar"
}
}
}
]
},
"x-bar": "API x-bar",
"servers": [
{
"url": "https://rznaap68yi.execute-api.ap-southeast-1.amazonaws.com/{basePath}",
"variables": {
"basePath": {
"default": "/test"
}
}
}
],
"components": {
"schemas": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger" : "2.0",
"info" : {
"description" : "API info description",
"version" : "2016-11-22T22:39:14Z",
"title" : "doc",
"x-bar" : "API info x-bar"
},
"host" : "rznaap68yi.execute-api.ap-southeast-1.amazonaws.com",
"basePath" : "/test",
"schemes" : [ "https" ],
"paths" : {
"/" : {
"get" : {
"description" : "Method description.",
"produces" : [ "application/json" ],
"responses" : {
"200" : {
"description" : "200 response",
"schema" : {
"$ref" : "#/definitions/Empty"
}
}
},
"x-example" : "x- Method example"
},
"x-bar" : "resource x-bar"
}
},
"definitions" : {
"Empty" : {
"type" : "object",
"title" : "Empty Schema"
}
},
"x-amazon-apigateway-documentation" : {
"version" : "1.0.0",
"createdDate" : "2016-11-22T22:41:40Z",
"documentationParts" : [ {
"location" : {
"type" : "API"
},
"properties" : {
"description" : "API description",
"foo" : "API foo",
"x-bar" : "API x-bar",
"info" : {
"description" : "API info description",
"version" : "API info version",
"foo" : "API info foo",
"x-bar" : "API info x-bar"
}
}
}, {
"location" : {
"type" : "METHOD",
"method" : "GET"
},
"properties" : {
"description" : "Method description.",
"x-example" : "x- Method example",
"foo" : "Method foo",
"info" : {
"version" : "method info version",
"description" : "method info description",
"foo" : "method info foo"
}
}
}, {
"location" : {
"type" : "RESOURCE"
},
"properties" : {
"description" : "resource description",
"foo" : "resource foo",
"x-bar" : "resource x-bar",
"info" : {
"description" : "resource info description",
"version" : "resource info version",
"foo" : "resource info foo",
"x-bar" : "resource info x-bar"
}
}
} ]
},
"x-bar" : "API x-bar"
}
```
------
설명서 부분의 `properties` 맵에 정의된 OpenAPI 호환 속성의 경우 API Gateway는 연결된 API 엔터티 정의에 속성을 삽입합니다. `x-something`의 속성은 표준 OpenAPI 확장입니다. 이 확장은 API 엔터티 정의에 전파됩니다. 예를 들어, `x-example` 메서드에 대한 `GET` 속성을 참조하십시오. `foo` 같은 속성은 OpenAPI 사양의 일부가 아니고 연결된 API 엔터티 정의에 삽입되지 않습니다.
설명서 렌더링 도구(예: [OpenAPI UI](https://swagger.io/tools/swagger-ui/))가 API 엔터티 정의를 구문 분석하여 설명서 속성을 추출할 경우, `properties` 인스턴스의 Swagger 비호환 `DocumentationPart` 속성은 도구에서 사용할 수 없습니다. 그러나 설명서 렌더링 도구에서 `x-amazon-apigateway-documentation` 객체를 구문 분석하여 콘텐츠를 가져오거나 도구에서 [restapi:documentation-parts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 및 [documenationpart:by-id](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationPart.html)를 호출하여 API Gateway에서 설명서 부분을 가져올 경우, 모든 설명서 속성을 도구에 사용하여 표시할 수 있습니다.
통합 세부 정보를 포함하는 API 엔터티가 있는 설명서를 JSON OpenAPI 파일로 내보내려면 다음 `GET` 요청을 제출하십시오.
```
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,documentation HTTP/1.1
Accept: application/json
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
```
통합 및 권한 부여자 세부 정보를 포함하는 API 엔터티가 있는 설명서를 YAML OpenAPI 파일로 내보내려면 다음 `GET` 요청을 제출하십시오.
```
GET /restapis/restapi_id/stages/stage_name/exports/swagger?extensions=integrations,authorizers,documentation HTTP/1.1
Accept: application/yaml
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
```
API Gateway 콘솔을 사용하여 API의 게시된 설명서를 내보내거나 다운로드하려면 [API Gateway 콘솔을 사용하여 REST API 내보내기](api-gateway-export-api.md#api-gateway-export-api-from-console)의 지침을 따릅니다.