# API Gateway의 REST API 문서 고객이 API를 이해하고 사용할 수 있도록 API를 문서화해야 합니다. API를 문서화하는 데 도움이 되도록 API Gateway에서는 개별 API 엔터티에 대한 도움말 콘텐츠를 API 개발 프로세스의 핵심 부분으로 추가하고 업데이트할 수 있습니다. API Gateway에서는 소스 콘텐츠가 저장되며 다양한 버전의 설명서를 보관할 수 있습니다. 설명서 버전을 API 단계와 연결하고, 단계별 설명서 스냅샷을 외부 OpenAPI 파일로 내보내고, 이 파일을 설명서 간행물로 배포할 수 있습니다. API를 문서화하려면 [API Gateway REST API](https://docs.aws.amazon.com/apigateway/latest/api/)를 호출하거나, API Gateway용 [AWS SDK](https://aws.amazon.com/developer/tools/) 중 하나를 사용하거나, API Gateway용 [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/apigateway/)를 사용하거나, API Gateway 콘솔을 사용할 수 있습니다. 또한 외부 OpenAPI 파일에 정의된 설명서 부분을 가져오거나 내보낼 수 있습니다. 개발자 포털을 사용하면 API 설명서를 개발자와 공유할 수 있습니다. 예제를 보려면 AWS 파트너 네트워크(APN) 블로그에서 [ReadMe를 API Gateway와 통합하여 개발자 허브를 최신 상태로 유지](https://aws.amazon.com/blogs/apn/integrating-readme-with-amazon-api-gateway-to-keep-your-developer-hub-up-to-date/) 또는 [SmartBear의 SwaggerHub를 사용하여 Amazon API Gateway에서 API 개발을 간소화하는 방법](https://aws.amazon.com/blogs/apn/how-to-streamline-api-development-on-amazon-api-gateway-using-smartbear-swaggerhub/)을 참조하세요. **Topics** + [API Gateway에 API 설명서 표시](api-gateway-documenting-api-content-representation.md) + [API Gateway 콘솔을 사용하여 API 문서화](api-gateway-documenting-api-quick-start-with-console.md) + [API Gateway 콘솔을 사용하여 API 설명서 게시](apigateway-documenting-api-with-console.md) + [API Gateway REST API를 사용하여 API 문서화](api-gateway-documenting-api-quick-start-with-restapi.md) + [API Gateway REST API를 사용하여 API 설명서 게시](api-gateway-documenting-api-quick-start-publishing.md) + [API 설명서 가져오기](api-gateway-documenting-api-quick-start-import-export.md) + [API Gateway에서 API 설명서에 대한 액세스 제어](api-gateway-documenting-api-content-provision-and-consumption.md) # API Gateway에 API 설명서 표시 API Gateway API 설명서는 API, 리소스, 메서드, 요청, 응답, 메시지 파라미터(즉 경로, 쿼리, 헤더)뿐 아니라 권한 부여자 및 모델을 포함하는 특정 API 엔터티와 연결된 개별 설명서 부분으로 구성됩니다. API Gateway에서 설명서 부분은 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 리소스로 표시됩니다. API 설명서 전체는 [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_GetDocumentationParts.html) 컬렉션으로 표시됩니다. API 문서화에는 API가 개선됨에 따라 `DocumentationPart` 인스턴스 생성, 인스턴스를 `DocumentationParts` 모음에 추가, 문서 부분의 버전을 관리하는 작업이 포함됩니다. **Topics** + [설명서 부분](#api-gateway-documenting-api-content-representation-documentation-parts) + [설명서 버전](#api-gateway-documenting-api-content-representation-documentation-versions) ## 설명서 부분 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 리소스는 개별 API 엔터티에 적용 가능한 설명서 콘텐츠를 저장하는 JSON 객체입니다. 여기에는 설명서의 모든 UTF-8 콘텐츠와 모든 주요 현지화 언어가 포함됩니다. `properties` 필드에는 설명서 콘텐츠가 키-값 페어의 맵으로 포함됩니다. `location` 속성은 연관된 API 엔터티를 식별합니다. 콘텐츠 맵의 형태는 API 개발자가 결정합니다. 키-값 페어의 값은 문자열, 숫자, 부울, 객체 또는 어레이일 수 있습니다. `location` 객체의 형태는 대상 엔터티 유형에 따라 결정됩니다. `DocumentationPart` 리소스는 콘텐츠 상속을 지원합니다. API 엔터티의 설명서 콘텐츠는 해당 API 엔터티의 하위에 적용됩니다. 하위 엔터티 및 콘텐츠 상속의 정의에 대한 자세한 내용은 [더 일반적인 사양의 API 엔터티에서 콘텐츠 상속](#api-gateway-documenting-api-content-inheritance) 단원을 참조하십시오. ### 설명서 부분의 위치 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 인스턴스의 [location](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#location) 속성은 연결된 콘텐츠가 적용되는 API 엔터티를 식별합니다. API 엔터티는 API Gateway REST API 리소스(예: [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html), [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html), [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html), [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html), [Authorizer](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) 또는 [Model](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html))일 수 있습니다. 엔터티는 URL 경로 파라미터, 쿼리 문자열 파라미터, 요청 또는 응답 헤더 파라미터, 요청 또는 응답 본문 또는 응답 상태 코드와 같은 메시지 파라미터일 수도 있습니다. API 엔터티를 지정하려면 `location` 객체의 [type](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#type) 속성을 `API`, `AUTHORIZER`, `MODEL`, `RESOURCE`, `METHOD`, `PATH_PARAMETER`, `QUERY_PARAMETER`, `REQUEST_HEADER`, `REQUEST_BODY`, `RESPONSE`, `RESPONSE_HEADER` 또는 `RESPONSE_BODY` 중 하나로 설정합니다. API 엔터티의 `type`에 따라 [method](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#method), [name](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#name), [path](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#path) 및 [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html#statusCode)를 포함한 기타 `location` 속성을 지정할 수 있습니다. 이러한 속성이 모두 특정 API 엔터티에 유효하지는 않습니다. 예를 들어 `type`, `path`, `name` 및 `statusCode`는 `RESPONSE` 엔터티의 유효한 속성이고, `type` 및 `path`만 `RESOURCE` 엔터티의 유효한 위치 속성입니다. 주어진 API 엔터티에 대해 `location`의 `DocumentationPart`에 잘못된 필드를 포함시키는 것은 오류입니다. 모든 유효한 `location` 필드가 필요하지는 않습니다. 예를 들어, `type`은 모든 API 엔터티의 유효한 필수 `location` 필드입니다. 그러나 `method`, `path` 및 `statusCode`는 유효하지만 `RESPONSE` 엔터티의 필수 속성은 아닙니다. 명시적으로 지정되지 않으면 유효한 `location` 필드는 기본값을 사용합니다. 기본 `path` 값은 `/`, 즉 API의 루트 리소스입니다. `method`의 기본값 또는 `statusCode`는 `*`입니다. 이는 각각 모든 메서드 또는 상태 코드 값을 의미합니다. ### 설명서 부분의 콘텐츠 `properties` 값은 JSON 문자열로 인코딩됩니다. `properties` 값에는 설명서 요구사항을 충족하기 위해 선택한 정보가 포함되어 있습니다. 예를 들어, 다음은 유효한 콘텐츠 맵입니다. ``` { "info": { "description": "My first API with Amazon API Gateway." }, "x-custom-info" : "My custom info, recognized by OpenAPI.", "my-info" : "My custom info not recognized by OpenAPI." } ``` API Gateway는 유효한 JSON 문자열을 콘텐츠 맵으로 허용하지만, 콘텐츠 속성은 OpenAPI에서 인식할 수 있는 범주와 인식할 수 없는 범주라는 두 가지 범주로 처리됩니다. 이전 예에서 `info`, `description` 및 `x-custom-info`는 OpenAPI에서 표준 OpenAPI 객체, 속성 또는 확장으로 인식합니다. 반대로 `my-info`는 OpenAPI 사양을 준수하지 않습니다. API Gateway는 OpenAPI 호환 콘텐츠 속성을 연결된 `DocumentationPart` 인스턴스의 API 엔터티 정의로 전파합니다. API Gateway는 비호환 콘텐츠 속성을 API 엔터티 정의로 전파하지 않습니다. 또 다른 예로, 여기에 `DocumentationPart` 엔터티를 대상으로 하는 `Resource`가 있습니다. ``` { "location" : { "type" : "RESOURCE", "path": "/pets" }, "properties" : { "summary" : "The /pets resource represents a collection of pets in PetStore.", "description": "... a child resource under the root...", } } ``` 여기서 `type` 및 `path`는 모두 `RESOURCE` 유형의 대상을 식별하는 데 유효한 필드입니다. 루트 리소스(`/`)의 경우, `path` 필드를 생략할 수 있습니다. ``` { "location" : { "type" : "RESOURCE" }, "properties" : { "description" : "The root resource with the default path specification." } } ``` 이는 다음 `DocumentationPart` 인스턴스와 동일합니다. ``` { "location" : { "type" : "RESOURCE", "path": "/" }, "properties" : { "description" : "The root resource with an explicit path specification" } } ``` ### 더 일반적인 사양의 API 엔터티에서 콘텐츠 상속 선택적 `location` 필드의 기본값은 API 엔터티의 패턴이 있는 설명을 제공합니다. `location` 객체의 기본값을 사용하면 이 `properties` 패턴 유형의 `DocumentationPart` 인스턴스에 `location` 맵의 일반적인 설명을 추가할 수 있습니다. 특정 엔터티에 연결된 `DocumentationPart` 인스턴스가 아직 없으면, API Gateway는 일반 API 엔터티의 `location`에서 적용 가능한 OpenAPI 설명서 속성을 추출하고 일반 `location` 패턴과 일치하거나 정확한 값과 일치하는 `DocumentationPart` 필드를 사용하여 특정 API 엔터티에 해당 속성을 주입합니다. 이 동작은 더 일반적인 사양의 API 엔터티에서 콘텐츠 상속이라고도 합니다. 콘텐츠 상속은 특정 API 개체 유형에는 적용되지 않습니다. 자세한 내용은 아래 표를 참조하십시오. API 엔터티가 둘 이상의 `DocumentationPart` 위치 패턴과 일치할 때 엔터티는 설명서 부분을 우선 순위가 가장 높은 위치 필드로 상속합니다. 우선 순위는 `path` > `statusCode`입니다. `path` 필드와 일치시키기 위해 API Gateway는 가장 구체적인 경로 값이 있는 엔터티를 선택합니다. 다음 표에는 몇 가지 예가 나와 있습니다. | 케이스 | `path` | `statusCode` | `name` | 설명 | | --- | --- | --- | --- | --- | | 1 | /pets | \$1 | id | 이 위치 패턴과 관련된 설명서는 위치 패턴과 일치하는 엔터티에 상속됩니다. | | 2 | /pets | 200 | id | 케이스 2가 케이스 1보다 더 구체적이기 때문에 이 위치 패턴과 관련된 문서는 케이스 1과 케이스 2가 일치할 때 위치 패턴과 일치하는 엔터티에 상속됩니다. | | 3 | /pets/petId | \$1 | id | 케이스 3이 케이스 2보다 우선 순위가 높고 케이스 1보다 구체적이기 때문에 케이스 1, 2 및 3이 일치할 때 이 위치 패턴과 관련된 문서가 위치 패턴과 일치하는 엔터티에 상속됩니다. | 보다 일반적인 `DocumentationPart` 인스턴스와 보다 구체적인 인스턴스를 대조하는 또 다른 예가 있습니다. 재정의되지 않는 한 다음과 같은 `"Invalid request error"`의 일반적인 오류 메시지가 `400` 오류 응답의 OpenAPI 정의에 삽입됩니다. ``` { "location" : { "type" : "RESPONSE", "statusCode": "400" }, "properties" : { "description" : "Invalid request error." }" } ``` 다음 덮어쓰기를 사용하면 `400` 리소스의 모든 메서드에 대한 `/pets` 응답에 `"Invalid petId specified"`가 대신 설명됩니다. ``` { "location" : { "type" : "RESPONSE", "path": "/pets", "statusCode": "400" }, "properties" : "{ "description" : "Invalid petId specified." }" } ``` ### `DocumentationPart`의 유효한 위치 필드 다음 표는 지정된 유형의 API 엔터티와 연결된 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 리소스의 적용 가능한 기본값과 유효 및 필수 필드를 보여줍니다. | API 엔터티 | 유효한 위치 필드 | 필수 위치 필드 | 기본 필드 값 | 상속 가능한 콘텐츠 | | --- | --- | --- | --- | --- | | [ API](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html) | 
{
    "location": {
        "type": "API" 
    }, 
    ... 
}
| type | 해당 사항 없음 | 아니요 | | [리소스](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) | 
{ 
    "location": { 
        "type": "RESOURCE", 
        "path": "resource_path" 
    }, 
    ... 
}
| type | path의 기본값은 /입니다. | 아니요 | | [방법](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) | 
{ 
    "location": { 
        "type": "METHOD", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}
| type | path 및 method의 기본값은 각각 / 및 \$1입니다. | 예, 접두사로 path를 매칭하고 모든 값의 method를 매칭합니다. | | 쿼리 파라미터 | 
{ 
    "location": { 
        "type": "QUERY_PARAMETER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "query_parameter_name" 
    }, 
    ... 
}
| type | path 및 method의 기본값은 각각 / 및 \$1입니다. | 예, 접두사로 path를 매칭하고 정확한 값으로 method를 매칭합니다. | | 요청 본문 | 
{ 
    "location": { 
        "type": "REQUEST_BODY", 
        "path": "resource_path", 
        "method": "http_verb" 
    }, 
    ... 
}
| type | path 및 method의 기본값은 각각 / 및 \$1입니다. | 예, 접두사로 path를 매칭하고 정확한 값으로 method를 매칭합니다. | | 요청 헤더 파라미터 | 
{ 
    "location": { 
        "type": "REQUEST_HEADER", 
        "path": "resource_path", 
        "method": "HTTP_verb",
        "name": "header_name" 
    }, 
    ... 
}
| type, name | path 및 method의 기본값은 각각 / 및 \$1입니다. | 예, 접두사로 path를 매칭하고 정확한 값으로 method를 매칭합니다. | | 요청 경로 파라미터 | 
{ 
    "location": { 
        "type": "PATH_PARAMETER", 
        "path": "resource/{path_parameter_name}", 
        "method": "HTTP_verb",
        "name": "path_parameter_name" 
    }, 
    ... 
}
| type, name | path 및 method의 기본값은 각각 / 및 \$1입니다. | 예, 접두사로 path를 매칭하고 정확한 값으로 method를 매칭합니다. | | 응답 | 
{ 
    "location": { 
        "type": "RESPONSE", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}
| type | path, method 및 statusCode의 기본값은 각각 /, \$1 및 \$1입니다. | 예, 접두사로 path를 매칭하고 정확한 값으로 method 및 statusCode를 매칭합니다. | | 응답 헤더 | 
{ 
    "location": { 
        "type": "RESPONSE_HEADER", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code", 
        "name": "header_name" 
    }, 
    ... 
}
| type, name | path, method 및 statusCode의 기본값은 각각 /, \$1 및 \$1입니다. | 예, 접두사로 path를 매칭하고 정확한 값으로 method 및 statusCode를 매칭합니다. | | 응답 본문 | 
{ 
    "location": { 
        "type": "RESPONSE_BODY", 
        "path": "resource_path", 
        "method": "http_verb", 
        "statusCode": "status_code" 
    }, 
    ... 
}
| type | path, method 및 statusCode의 기본값은 각각 /, \$1 및 \$1입니다. | 예, 접두사로 path를 매칭하고 정확한 값으로 method 및 statusCode를 매칭합니다. | | [권한 부여자](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html) | 
{ 
    "location": { 
        "type": "AUTHORIZER", 
        "name": "authorizer_name" 
    }, 
    ... 
}
| type | 해당 사항 없음 | 아니요 | | [모델](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) | 
{ 
    "location": { 
        "type": "MODEL", 
        "name": "model_name" 
    }, 
    ... 
}
| type | 해당 사항 없음 | 아니요 | ## 설명서 버전 설명서 버전은 API의 [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 컬렉션에 대한 스냅샷이며 버전 식별자로 태그 지정됩니다. API의 설명서를 게시하려면 설명서 버전을 만들고 이를 API 단계와 연결하고 API 설명서의 해당 단계별 버전을 외부 OpenAPI 파일로 내보내는 작업이 필요합니다. API Gateway에서 설명서 스냅샷은 [DocumentationVersion](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) 리소스로 표시됩니다. API를 업데이트하면 새 버전의 API가 만들어집니다. API Gateway에서는 [DocumentationVersions](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationVersion.html) 컬렉션을 사용하여 모든 설명서 버전을 유지 관리합니다. # API Gateway 콘솔을 사용하여 API 문서화 이 단원에서는 API Gateway 콘솔을 사용하여 API의 설명서 부분을 생성하고 유지 관리하는 방법에 대해 설명합니다. API의 설명서를 작성하고 편집하기 위한 전제 조건으로 API를 이미 작성했어야 합니다. 이 단원에서는 [PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets) API를 예로 사용합니다. API Gateway 콘솔을 사용하여 API를 생성하려면 [자습서: 예제를 가져와 REST API 생성](api-gateway-create-api-from-example.md)의 지침을 따릅니다. **Topics** + [`API` 엔터티 문서화](#api-gateway-document-api-add-document-part-for-api-entity-with-console) + [`RESOURCE` 엔터티 문서화](#api-gateway-document-api-add-document-part-for-resource-entity-with-console) + [`METHOD` 엔터티 문서화](#api-gateway-document-api-add-document-part-for-method-entity-with-console) + [`QUERY_PARAMETER` 엔터티 문서화](#api-gateway-document-api-add-document-part-for-request-query-entity-with-console) + [`PATH_PARAMETER` 엔터티 문서화](#api-gateway-document-api-add-document-part-for-path-parameter-entity-with-console) + [`REQUEST_HEADER` 엔터티 문서화](#api-gateway-document-api-add-document-part-for-request-header-entity-with-console) + [`REQUEST_BODY` 엔터티 문서화](#api-gateway-document-api-add-document-part-for-request-body-entity-with-console) + [`RESPONSE` 엔터티 문서화](#api-gateway-document-api-add-document-part-for-response-with-console) + [`RESPONSE_HEADER` 엔터티 문서화](#api-gateway-document-api-add-document-part-for-response-header-entity-with-console) + [`RESPONSE_BODY` 엔터티 문서화](#api-gateway-document-api-add-document-part-for-response-body-entity-with-console) + [`MODEL` 엔터티 문서화](#api-gateway-document-api-add-document-part-for-model-entity-with-console) + [`AUTHORIZER` 엔터티 문서화](#api-gateway-document-api-add-document-part-for-authorizer-entity-with-console) ## `API` 엔터티 문서화 `API` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다. 1. 기본 탐색 창에서 **설명서**를 선택한 다음 **설명서 부분 생성**을 선택합니다. 1. **설명서 유형**에서 **API**를 선택합니다. 설명서 부분이 `API`용으로 생성되지 않은 경우, 설명서 부분의 `properties` 맵 편집기를 가져옵니다. 텍스트 편집기에 다음 `properties` 맵을 입력합니다. ``` { "info": { "description": "Your first API Gateway API.", "contact": { "name": "John Doe", "email": "john.doe@api.com" } } } ``` **참고** `properties` 맵을 JSON 문자열에 인코딩할 필요가 없습니다. API Gateway 콘솔은 JSON 객체를 자동으로 문자열화합니다. 1. **설명서 부분 생성**을 선택합니다. **리소스** 창에서 `API` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다. 1. 기본 탐색 창에서 **리소스**를 선택합니다. 1. **API 작업** 메뉴를 선택한 다음 **API 설명서 업데이트**를 선택합니다. ![\[API Gateway 콘솔에서 API 엔터티에 대한 설명서 편집\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/document-api-entity-using-new-console.png) 기존 설명서 부분을 편집하려면 다음을 수행합니다. 1. **설명서** 창에서 **리소스 및 메서드** 탭을 선택합니다. 1. API 이름을 선택한 다음 API 카드에서 **편집**을 선택합니다. ## `RESOURCE` 엔터티 문서화 `RESOURCE` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다. 1. 기본 탐색 창에서 **설명서**를 선택한 다음 **설명서 부분 생성**을 선택합니다. 1. **설명서 유형**에서 **리소스**를 선택합니다. 1. **경로**에 경로를 입력합니다. 1. 텍스트 편집기에서 설명을 입력합니다. 예를 들면 다음과 같습니다. ``` { "description": "The PetStore's root resource." } ``` 1. **설명서 부분 생성**을 선택합니다. 목록에 없는 리소스에 대한 설명서를 생성할 수 있습니다. 1. 필요한 경우 이 단계를 반복하여 다른 설명서 부분을 추가하거나 편집합니다. **리소스** 창에서 `RESOURCE` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다. 1. 기본 탐색 창에서 **리소스**를 선택합니다. 1. 리소스를 선택한 다음 **설명서 업데이트**를 선택합니다. ![\[API Gateway 콘솔에서 리소스 엔터티에 대한 설명서 편집\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/document-resource-entity-using-new-console.png) 기존 설명서 부분을 편집하려면 다음을 수행합니다. 1. **설명서** 창에서 **리소스 및 메서드** 탭을 선택합니다. 1. 설명서 부분이 포함된 리소스를 선택한 다음 **편집**을 선택합니다. ## `METHOD` 엔터티 문서화 `METHOD` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다. 1. 기본 탐색 창에서 **설명서**를 선택한 다음 **설명서 부분 생성**을 선택합니다. 1. **설명서 유형**에서 **메서드**를 선택합니다. 1. **경로**에 경로를 입력합니다. 1. **메서드**에서 HTTP 동사를 선택합니다. 1. 텍스트 편집기에서 설명을 입력합니다. 예를 들면 다음과 같습니다. ``` { "tags" : [ "pets" ], "summary" : "List all pets" } ``` 1. **설명서 부분 생성**을 선택합니다. 목록에 없는 메서드에 대한 설명서를 생성할 수 있습니다. 1. 필요한 경우 이 단계를 반복하여 다른 설명서 부분을 추가하거나 편집합니다. **리소스** 창에서 `METHOD` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다. 1. 기본 탐색 창에서 **리소스**를 선택합니다. 1. 메서드를 선택한 다음 **설명서 업데이트**를 선택합니다. ![\[API Gateway 콘솔에서 메서드 엔터티에 대한 설명서 편집\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/document-method-entity-using-new-console.png) 기존 설명서 부분을 편집하려면 다음을 수행합니다. 1. **설명서** 창에서 **리소스 및 메서드** 탭을 선택합니다. 1. 메서드를 선택하거나 메서드가 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다. 1. **편집**을 선택합니다. ## `QUERY_PARAMETER` 엔터티 문서화 `QUERY_PARAMETER` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다. 1. 기본 탐색 창에서 **설명서**를 선택한 다음 **설명서 부분 생성**을 선택합니다. 1. **설명서 유형**에서 **쿼리 파라미터**를 선택합니다. 1. **경로**에 경로를 입력합니다. 1. **메서드**에서 HTTP 동사를 선택합니다. 1. **이름**에 이름을 입력합니다. 1. 텍스트 편집기에서 설명을 입력합니다. 1. **설명서 부분 생성**을 선택합니다. 목록에 없는 쿼리 파라미터에 대한 설명서를 생성할 수 있습니다. 1. 필요한 경우 이 단계를 반복하여 다른 설명서 부분을 추가하거나 편집합니다. 기존 설명서 부분을 편집하려면 다음을 수행합니다. 1. **설명서** 창에서 **리소스 및 메서드** 탭을 선택합니다. 1. 쿼리 파라미터를 선택하거나 쿼리 파라미터가 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다. 1. **편집**을 선택합니다. ## `PATH_PARAMETER` 엔터티 문서화 `PATH_PARAMETER` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다. 1. 기본 탐색 창에서 **설명서**를 선택한 다음 **설명서 부분 생성**을 선택합니다. 1. **설명서 유형**에서 **경로 파라미터**를 선택합니다. 1. **경로**에 경로를 입력합니다. 1. **메서드**에서 HTTP 동사를 선택합니다. 1. **이름**에 이름을 입력합니다. 1. 텍스트 편집기에서 설명을 입력합니다. 1. **설명서 부분 생성**을 선택합니다. 목록에 없는 경로 파라미터에 대한 설명서를 생성할 수 있습니다. 1. 필요한 경우 이 단계를 반복하여 다른 설명서 부분을 추가하거나 편집합니다. 기존 설명서 부분을 편집하려면 다음을 수행합니다. 1. **설명서** 창에서 **리소스 및 메서드** 탭을 선택합니다. 1. 경로 파라미터를 선택하거나 경로 파라미터가 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다. 1. **편집**을 선택합니다. ## `REQUEST_HEADER` 엔터티 문서화 `REQUEST_HEADER` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다. 1. 기본 탐색 창에서 **설명서**를 선택한 다음 **설명서 부분 생성**을 선택합니다. 1. **설명서 유형**에서 **요청 헤더**를 선택합니다. 1. **경로**에 요청 헤더의 경로를 입력합니다. 1. **메서드**에서 HTTP 동사를 선택합니다. 1. **이름**에 이름을 입력합니다. 1. 텍스트 편집기에서 설명을 입력합니다. 1. **설명서 부분 생성**을 선택합니다. 목록에 없는 요청 헤더에 대한 설명서를 생성할 수 있습니다. 1. 필요한 경우 이 단계를 반복하여 다른 설명서 부분을 추가하거나 편집합니다. 기존 설명서 부분을 편집하려면 다음을 수행합니다. 1. **설명서** 창에서 **리소스 및 메서드** 탭을 선택합니다. 1. 요청 헤더를 선택하거나 요청 헤더가 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다. 1. **편집**을 선택합니다. ## `REQUEST_BODY` 엔터티 문서화 `REQUEST_BODY` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다. 1. 기본 탐색 창에서 **설명서**를 선택한 다음 **설명서 부분 생성**을 선택합니다. 1. **설명서 유형**에서 **요청 본문**을 선택합니다. 1. **경로**에 요청 본문의 경로를 입력합니다. 1. **메서드**에서 HTTP 동사를 선택합니다. 1. 텍스트 편집기에서 설명을 입력합니다. 1. **설명서 부분 생성**을 선택합니다. 목록에 없는 요청 본문에 대한 설명서를 생성할 수 있습니다. 1. 필요한 경우 이 단계를 반복하여 다른 설명서 부분을 추가하거나 편집합니다. 기존 설명서 부분을 편집하려면 다음을 수행합니다. 1. **설명서** 창에서 **리소스 및 메서드** 탭을 선택합니다. 1. 요청 본문을 선택하거나 요청 본문이 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다. 1. **편집**을 선택합니다. ## `RESPONSE` 엔터티 문서화 `RESPONSE` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다. 1. 기본 탐색 창에서 **설명서**를 선택한 다음 **설명서 부분 생성**을 선택합니다. 1. **설명서 유형**에서 **응답(상태 코드)**을 선택합니다. 1. **경로**에 응답의 경로를 입력합니다. 1. **메서드**에서 HTTP 동사를 선택합니다. 1. **상태 코드**에 HTTP 상태 코드를 입력합니다. 1. 텍스트 편집기에서 설명을 입력합니다. 1. **설명서 부분 생성**을 선택합니다. 목록에 없는 응답 상태 코드에 대한 설명서를 생성할 수 있습니다. 1. 필요한 경우 이 단계를 반복하여 다른 설명서 부분을 추가하거나 편집합니다. 기존 설명서 부분을 편집하려면 다음을 수행합니다. 1. **설명서** 창에서 **리소스 및 메서드** 탭을 선택합니다. 1. 응답 상태 코드를 선택하거나 응답 상태 코드가 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다. 1. **편집**을 선택합니다. ## `RESPONSE_HEADER` 엔터티 문서화 `RESPONSE_HEADER` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다. 1. 기본 탐색 창에서 **설명서**를 선택한 다음 **설명서 부분 생성**을 선택합니다. 1. **설명서 유형**에서 **응답 헤더**를 선택합니다. 1. **경로**에 응답 헤더의 경로를 입력합니다. 1. **메서드**에서 HTTP 동사를 선택합니다. 1. **상태 코드**에 HTTP 상태 코드를 입력합니다. 1. 텍스트 편집기에서 설명을 입력합니다. 1. **설명서 부분 생성**을 선택합니다. 목록에 없는 응답 헤더에 대한 설명서를 생성할 수 있습니다. 1. 필요한 경우 이 단계를 반복하여 다른 설명서 부분을 추가하거나 편집합니다. 기존 설명서 부분을 편집하려면 다음을 수행합니다. 1. **설명서** 창에서 **리소스 및 메서드** 탭을 선택합니다. 1. 응답 헤더를 선택하거나 응답 헤더가 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다. 1. **편집**을 선택합니다. ## `RESPONSE_BODY` 엔터티 문서화 `RESPONSE_BODY` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다. 1. 기본 탐색 창에서 **설명서**를 선택한 다음 **설명서 부분 생성**을 선택합니다. 1. **설명서 유형**에서 **응답 본문**을 선택합니다. 1. **경로**에 응답 본문의 경로를 입력합니다. 1. **메서드**에서 HTTP 동사를 선택합니다. 1. **상태 코드**에 HTTP 상태 코드를 입력합니다. 1. 텍스트 편집기에서 설명을 입력합니다. 1. **설명서 부분 생성**을 선택합니다. 목록에 없는 응답 본문에 대한 설명서를 생성할 수 있습니다. 1. 필요한 경우 이 단계를 반복하여 다른 설명서 부분을 추가하거나 편집합니다. 기존 설명서 부분을 편집하려면 다음을 수행합니다. 1. **설명서** 창에서 **리소스 및 메서드** 탭을 선택합니다. 1. 응답 본문을 선택하거나 응답 본문이 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다. 1. **편집**을 선택합니다. ## `MODEL` 엔터티 문서화 `MODEL` 엔터티를 문서화하려면 해당 모델의 `DocumentPart` 인스턴스 및 각각의 `properties`를 생성하고 관리해야 합니다. 예를 들어, 기본적으로 모든 API와 함께 제공되는 `Error` 모델에는 다음과 같은 스키마 정의가 있습니다. ``` { "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "Error Schema", "type" : "object", "properties" : { "message" : { "type" : "string" } } } ``` 그리고 두 개의 `DocumentationPart` 인스턴스가 필요합니다. 하나는 `Model`용이고 다른 하나는 `message` 속성용입니다. ``` { "location": { "type": "MODEL", "name": "Error" }, "properties": { "title": "Error Schema", "description": "A description of the Error model" } } ``` 및 ``` { "location": { "type": "MODEL", "name": "Error.message" }, "properties": { "description": "An error message." } } ``` API를 내보낼 경우 `DocumentationPart`'의 속성이 원본 스키마의 값을 재정의합니다. `MODEL` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다. 1. 기본 탐색 창에서 **설명서**를 선택한 다음 **설명서 부분 생성**을 선택합니다. 1. **설명서 유형**에서 **모델**을 선택합니다. 1. **이름**에 모델의 이름을 입력합니다. 1. 텍스트 편집기에서 설명을 입력합니다. 1. **설명서 부분 생성**을 선택합니다. 목록에 없는 모델에 대한 설명서를 생성할 수 있습니다. 1. 필요한 경우 이 단계를 반복하여 설명서 부분을 다른 모델에 추가하거나 편집합니다. **모델** 창에서 `MODEL` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다. 1. 기본 탐색 창에서 **모델**을 선택합니다. 1. 모델을 선택한 다음 **설명서 업데이트**를 선택합니다. ![\[API Gateway 콘솔에서 모델 엔터티에 대한 설명서 편집\]](http://docs.aws.amazon.com/ko_kr/apigateway/latest/developerguide/images/document-model-entity-using-new-console.png) 기존 설명서 부분을 편집하려면 다음을 수행합니다. 1. **설명서** 창에서 **모델** 탭을 선택합니다. 1. 검색 창을 사용하거나 모델을 선택한 다음 **편집**을 선택합니다. ## `AUTHORIZER` 엔터티 문서화 `AUTHORIZER` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다. 1. 기본 탐색 창에서 **설명서**를 선택한 다음 **설명서 부분 생성**을 선택합니다. 1. **설명서 유형**에서 **권한 부여자**를 선택합니다. 1. **이름**에 권한 부여자 이름을 입력합니다. 1. 텍스트 편집기에서 설명을 입력합니다. 권한 부여자에 대한 유효한 `location` 필드의 값을 지정합니다. 1. **설명서 부분 생성**을 선택합니다. 목록에 없는 권한 부여자에 대한 설명서를 생성할 수 있습니다. 1. 필요한 경우 이 단계를 반복하여 설명서 부분을 다른 권한 부여자에 추가하거나 편집합니다. 기존 설명서 부분을 편집하려면 다음을 수행합니다. 1. **설명서** 창에서 **권한 부여자** 탭을 선택합니다. 1. 검색 창을 사용하거나 권한 부여자를 선택한 다음 **편집**을 선택합니다. # API Gateway 콘솔을 사용하여 API 설명서 게시 다음 절차에서는 설명서 버전을 게시하는 방법을 설명합니다. **API Gateway 콘솔을 사용하여 설명서 버전을 게시하려면** 1. 기본 탐색 창에서 **설명서**를 선택합니다. 1. **설명서 게시**를 선택합니다. 1. 출판 설정: 1. **스테이지**에서 스테이지를 선택합니다. 1. **버전**에 버전 식별자(예: `1.0.0`)를 입력합니다. 1. (선택 사항) **설명**에 설명을 입력합니다. 1. [**Publish**]를 선택합니다. 이제 설명서를 외부 OpenAPI 파일로 내보내서 게시된 설명서를 다운로드할 수 있습니다. 자세한 내용은 [API Gateway에서 REST API 내보내기](api-gateway-export-api.md) 단원을 참조하십시오. # API Gateway REST API를 사용하여 API 문서화 이 단원에서는 API Gateway REST API를 사용하여 API의 설명서 부분을 생성하고 유지 관리하는 방법에 대해 설명합니다. API 설명서를 생성 및 편집하기 전에 먼저 API를 만드십시오. 이 단원에서는 [PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets) API를 예로 사용합니다. API Gateway 콘솔을 사용하여 API를 생성하려면 [자습서: 예제를 가져와 REST API 생성](api-gateway-create-api-from-example.md)의 지침을 따릅니다. **Topics** + [`API` 엔터티 문서화](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-api) + [`RESOURCE` 엔터티 문서화](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-resource) + [`METHOD` 엔터티 문서화](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-method) + [`QUERY_PARAMETER` 엔터티 문서화](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-query-parameter) + [`PATH_PARAMETER` 엔터티 문서화](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-path-parameter) + [`REQUEST_BODY` 엔터티 문서화](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-request-body) + [`REQUEST_HEADER` 엔터티 문서화](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-request-header) + [`RESPONSE` 엔터티 문서화](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-response) + [`RESPONSE_HEADER` 엔터티 문서화](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-response-header) + [`AUTHORIZER` 엔터티 문서화](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-authorizer) + [`MODEL` 엔터티 문서화](#api-gateway-documenting-api-quick-start-with-restapi-add-content-to-model) + [설명서 부분 업데이트](#api-gateway-documenting-api-quick-start-with-restapi-update-content) + [설명서 부분 나열](#api-gateway-documenting-api-quick-start-with-restapi-list-parts) ## `API` 엔터티 문서화 [API](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)에 대한 설명서를 추가하려면 API 엔터티에 대한 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 리소스를 추가합니다. ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "API" }, "properties": "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}" } ``` 성공하면 해당 작업은 페이로드에서 새로 생성된 `201 Created` 인스턴스를 포함하는 `DocumentationPart` 응답을 반환합니다. 예: ``` { ... "id": "s2e5xf", "location": { "path": null, "method": null, "name": null, "statusCode": null, "type": "API" }, "properties": "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}" } ``` 설명서 부분이 이미 추가된 경우 `409 Conflict`의 오류 메시지를 포함하여 `Documentation part already exists for the specified location: type 'API'."` 응답이 반환됩니다. 이 경우 [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html) 작업을 호출해야 합니다. ``` PATCH /restapis/4wk1k4onj3/documentation/parts/part_id 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" : "/properties", "value" : "{\n\t\"info\": {\n\t\t\"description\" : \"Your first API with Amazon API Gateway.\"\n\t}\n}" } ] } ``` 응답이 성공하면 업데이트된 `200 OK` 인스턴스를 포함한 페이로드와 함께 `DocumentationPart` 상태 코드를 반환합니다. ## `RESOURCE` 엔터티 문서화 API의 루트 리소스에 대한 설명서를 추가하려면 해당 [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) 리소스를 대상으로 하는 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 리소스를 추가합니다. ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "RESOURCE", }, "properties" : "{\n\t\"description\" : \"The PetStore root resource.\"\n}" } ``` 성공하면 해당 작업은 페이로드에서 새로 생성된 `201 Created` 인스턴스를 포함하는 `DocumentationPart` 응답을 반환합니다. 예: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/p76vqo" } }, "id": "p76vqo", "location": { "path": "/", "method": null, "name": null, "statusCode": null, "type": "RESOURCE" }, "properties": "{\n\t\"description\" : \"The PetStore root resource.\"\n}" } ``` 리소스 경로가 지정되지 않은 경우 리소스가 루트 리소스로 간주됩니다. `"path": "/"`를 `properties`에 추가하여 명시적으로 지정할 수 있습니다. API의 하위 리소스에 대한 설명서를 추가하려면 해당 [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) 리소스를 대상으로 하는 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 리소스를 추가합니다. ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "RESOURCE", "path" : "/pets" }, "properties": "{\n\t\"description\" : \"A child resource under the root of PetStore.\"\n}" } ``` 성공하면 해당 작업은 페이로드에서 새로 생성된 `201 Created` 인스턴스를 포함하는 `DocumentationPart` 응답을 반환합니다. 예: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/qcht86" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/qcht86" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/qcht86" } }, "id": "qcht86", "location": { "path": "/pets", "method": null, "name": null, "statusCode": null, "type": "RESOURCE" }, "properties": "{\n\t\"description\" : \"A child resource under the root of PetStore.\"\n}" } ``` 경로 파라미터로 지정된 하위 리소스에 대한 설명서를 추가하려면 [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) 리소스를 대상으로 하는 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 리소스를 추가합니다. ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "RESOURCE", "path" : "/pets/{petId}" }, "properties": "{\n\t\"description\" : \"A child resource specified by the petId path parameter.\"\n}" } ``` 성공하면 해당 작업은 페이로드에서 새로 생성된 `201 Created` 인스턴스를 포함하는 `DocumentationPart` 응답을 반환합니다. 예: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/k6fpwb" } }, "id": "k6fpwb", "location": { "path": "/pets/{petId}", "method": null, "name": null, "statusCode": null, "type": "RESOURCE" }, "properties": "{\n\t\"description\" : \"A child resource specified by the petId path parameter.\"\n}" } ``` **참고** `RESOURCE` 엔터티의 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 인스턴스는 하위 리소스가 상속할 수 없습니다. ## `METHOD` 엔터티 문서화 API의 메서드에 대한 설명서를 추가하려면 해당 [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) 리소스를 대상으로 하는 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 리소스를 추가합니다. ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "METHOD", "path" : "/pets", "method" : "GET" }, "properties": "{\n\t\"summary\" : \"List all pets.\"\n}" } ``` 성공하면 해당 작업은 페이로드에서 새로 생성된 `201 Created` 인스턴스를 포함하는 `DocumentationPart` 응답을 반환합니다. 예: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" } }, "id": "o64jbj", "location": { "path": "/pets", "method": "GET", "name": null, "statusCode": null, "type": "METHOD" }, "properties": "{\n\t\"summary\" : \"List all pets.\"\n}" } ``` 성공하면 해당 작업은 페이로드에서 새로 생성된 `201 Created` 인스턴스를 포함하는 `DocumentationPart` 응답을 반환합니다. 예: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" } }, "id": "o64jbj", "location": { "path": "/pets", "method": "GET", "name": null, "statusCode": null, "type": "METHOD" }, "properties": "{\n\t\"summary\" : \"List all pets.\"\n}" } ``` 이전 요청에서 `location.method` 필드가 지정되지 않은 경우 와일드카드 `ANY` 문자로 표현되는 `*` 메서드로 간주됩니다. `METHOD` 엔터티의 설명서 콘텐츠를 업데이트하려면 [documentationpart:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDocumentationPart.html) 작업을 호출하여 새 `properties` 맵을 제공합니다. ``` PATCH /restapis/4wk1k4onj3/documentation/parts/part_id 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" : "/properties", "value" : "{\n\t\"tags\" : [ \"pets\" ], \n\t\"summary\" : \"List all pets.\"\n}" } ] } ``` 응답이 성공하면 업데이트된 `200 OK` 인스턴스를 포함한 페이로드와 함께 `DocumentationPart` 상태 코드를 반환합니다. 예: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/o64jbj" } }, "id": "o64jbj", "location": { "path": "/pets", "method": "GET", "name": null, "statusCode": null, "type": "METHOD" }, "properties": "{\n\t\"tags\" : [ \"pets\" ], \n\t\"summary\" : \"List all pets.\"\n}" } ``` ## `QUERY_PARAMETER` 엔터티 문서화 요청 쿼리 파라미터에 대한 설명서를 추가하려면 `QUERY_PARAMETER` 및 `path`의 유효한 필드를 사용하여 `name` 유형을 대상으로 하는 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 리소스를 추가합니다. ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "QUERY_PARAMETER", "path" : "/pets", "method" : "GET", "name" : "page" }, "properties": "{\n\t\"description\" : \"Page number of results to return.\"\n}" } ``` 성공하면 해당 작업은 페이로드에서 새로 생성된 `201 Created` 인스턴스를 포함하는 `DocumentationPart` 응답을 반환합니다. 예: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/h9ht5w" } }, "id": "h9ht5w", "location": { "path": "/pets", "method": "GET", "name": "page", "statusCode": null, "type": "QUERY_PARAMETER" }, "properties": "{\n\t\"description\" : \"Page number of results to return.\"\n}" } ``` `properties` 엔터티의 설명서 부분의 `QUERY_PARAMETER` 맵은 `QUERY_PARAMETER` 하위 엔터티 중 하나만 상속할 수 있습니다. 예를 들어, `treats` 다음에 `/pets/{petId}` 리소스를 추가하고, `GET`에서 `/pets/{petId}/treats` 메서드를 활성화하고, `page` 쿼리 파라미터를 표시한 경우, 사용자가 `DocumentationPart` 리소스를 `properties` 메서드의 `GET /pets` 쿼리 파라미터에 명시적으로 추가하지 않으면 이 하위 쿼리 파라미터는 `DocumentationPart` 메서드의 이름이 같은 쿼리 파라미터에서 `page`의 `GET /pets/{petId}/treats` 맵을 상속합니다. ## `PATH_PARAMETER` 엔터티 문서화 경로 파라미터에 대한 설명서를 추가하려면 `PATH_PARAMETER` 엔터티에 대한 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 리소스를 추가합니다. ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "PATH_PARAMETER", "path" : "/pets/{petId}", "method" : "*", "name" : "petId" }, "properties": "{\n\t\"description\" : \"The id of the pet to retrieve.\"\n}" } ``` 성공하면 해당 작업은 페이로드에서 새로 생성된 `201 Created` 인스턴스를 포함하는 `DocumentationPart` 응답을 반환합니다. 예: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/ckpgog" } }, "id": "ckpgog", "location": { "path": "/pets/{petId}", "method": "*", "name": "petId", "statusCode": null, "type": "PATH_PARAMETER" }, "properties": "{\n \"description\" : \"The id of the pet to retrieve\"\n}" } ``` ## `REQUEST_BODY` 엔터티 문서화 요청 본문에 대한 설명서를 추가하려면 요청 본문에 대한 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 리소스를 추가합니다. ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "REQUEST_BODY", "path" : "/pets", "method" : "POST" }, "properties": "{\n\t\"description\" : \"A Pet object to be added to PetStore.\"\n}" } ``` 성공하면 해당 작업은 페이로드에서 새로 생성된 `201 Created` 인스턴스를 포함하는 `DocumentationPart` 응답을 반환합니다. 예: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/kgmfr1" } }, "id": "kgmfr1", "location": { "path": "/pets", "method": "POST", "name": null, "statusCode": null, "type": "REQUEST_BODY" }, "properties": "{\n\t\"description\" : \"A Pet object to be added to PetStore.\"\n}" } ``` ## `REQUEST_HEADER` 엔터티 문서화 요청 헤더에 대한 설명서를 추가하려면 요청 헤더에 대한 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 리소스를 추가합니다. ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "REQUEST_HEADER", "path" : "/pets", "method" : "GET", "name" : "x-my-token" }, "properties": "{\n\t\"description\" : \"A custom token used to authorization the method invocation.\"\n}" } ``` 성공하면 해당 작업은 페이로드에서 새로 생성된 `201 Created` 인스턴스를 포함하는 `DocumentationPart` 응답을 반환합니다. 예: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/h0m3uf" } }, "id": "h0m3uf", "location": { "path": "/pets", "method": "GET", "name": "x-my-token", "statusCode": null, "type": "REQUEST_HEADER" }, "properties": "{\n\t\"description\" : \"A custom token used to authorization the method invocation.\"\n}" } ``` ## `RESPONSE` 엔터티 문서화 상태 코드의 응답에 대한 설명서를 추가하려면 해당 [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) 리소스를 대상으로 하는 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 리소스를 추가합니다. ``` POST /restapis/restapi_id/documentation/parts 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 { "location": { "path": "/", "method": "*", "name": null, "statusCode": "200", "type": "RESPONSE" }, "properties": "{\n \"description\" : \"Successful operation.\"\n}" } ``` 성공하면 해당 작업은 페이로드에서 새로 생성된 `201 Created` 인스턴스를 포함하는 `DocumentationPart` 응답을 반환합니다. 예: ``` { "_links": { "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/lattew" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/lattew" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/lattew" } }, "id": "lattew", "location": { "path": "/", "method": "*", "name": null, "statusCode": "200", "type": "RESPONSE" }, "properties": "{\n \"description\" : \"Successful operation.\"\n}" } ``` ## `RESPONSE_HEADER` 엔터티 문서화 응답 헤더에 대한 설명서를 추가하려면 응답 헤더에 대한 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 리소스를 추가합니다. ``` POST /restapis/restapi_id/documentation/parts 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 "location": { "path": "/", "method": "GET", "name": "Content-Type", "statusCode": "200", "type": "RESPONSE_HEADER" }, "properties": "{\n \"description\" : \"Media type of request\"\n}" ``` 성공하면 해당 작업은 페이로드에서 새로 생성된 `201 Created` 인스턴스를 포함하는 `DocumentationPart` 응답을 반환합니다. 예: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/fev7j7" } }, "id": "fev7j7", "location": { "path": "/", "method": "GET", "name": "Content-Type", "statusCode": "200", "type": "RESPONSE_HEADER" }, "properties": "{\n \"description\" : \"Media type of request\"\n}" } ``` 이 `Content-Type` 응답 헤더의 설명서는 모든 API 응답의 `Content-Type` 헤더에 대한 기본 설명서입니다. ## `AUTHORIZER` 엔터티 문서화 API 권한 부여자에 대한 설명서를 추가하려면 지정된 권한 부여자를 대상으로 하는 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 리소스를 추가합니다. ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "AUTHORIZER", "name" : "myAuthorizer" }, "properties": "{\n\t\"description\" : \"Authorizes invocations of configured methods.\"\n}" } ``` 성공하면 해당 작업은 페이로드에서 새로 생성된 `201 Created` 인스턴스를 포함하는 `DocumentationPart` 응답을 반환합니다. 예: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/pw3qw3" } }, "id": "pw3qw3", "location": { "path": null, "method": null, "name": "myAuthorizer", "statusCode": null, "type": "AUTHORIZER" }, "properties": "{\n\t\"description\" : \"Authorizes invocations of configured methods.\"\n}" } ``` **참고** `AUTHORIZER` 엔터티의 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 인스턴스는 하위 리소스가 상속할 수 없습니다. ## `MODEL` 엔터티 문서화 `MODEL` 엔터티를 문서화하려면 해당 모델의 `DocumentPart` 인스턴스 및 각각의 `properties`를 생성하고 관리해야 합니다. 예를 들어, 기본적으로 모든 API와 함께 제공되는 `Error` 모델에는 다음과 같은 스키마 정의가 있습니다. ``` { "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "Error Schema", "type" : "object", "properties" : { "message" : { "type" : "string" } } } ``` 그리고 두 개의 `DocumentationPart` 인스턴스가 필요합니다. 하나는 `Model`용이고 다른 하나는 `message` 속성용입니다. ``` { "location": { "type": "MODEL", "name": "Error" }, "properties": { "title": "Error Schema", "description": "A description of the Error model" } } ``` 및 ``` { "location": { "type": "MODEL", "name": "Error.message" }, "properties": { "description": "An error message." } } ``` API를 내보낼 경우 `DocumentationPart`'의 속성이 원본 스키마의 값을 재정의합니다. API 모델에 대한 설명서를 추가하려면 지정된 모델을 대상으로 하는 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 리소스를 추가합니다. ``` POST /restapis/restapi_id/documentation/parts 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 { "location" : { "type" : "MODEL", "name" : "Pet" }, "properties": "{\n\t\"description\" : \"Data structure of a Pet object.\"\n}" } ``` 성공하면 해당 작업은 페이로드에서 새로 생성된 `201 Created` 인스턴스를 포함하는 `DocumentationPart` 응답을 반환합니다. 예: ``` { "_links": { "curies": { "href": "http://docs.aws.amazon.com/apigateway/latest/developerguide/restapi-documentationpart-{rel}.html", "name": "documentationpart", "templated": true }, "self": { "href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq" }, "documentationpart:delete": { "href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq" }, "documentationpart:update": { "href": "/restapis/4wk1k4onj3/documentation/parts/lkn4uq" } }, "id": "lkn4uq", "location": { "path": null, "method": null, "name": "Pet", "statusCode": null, "type": "MODEL" }, "properties": "{\n\t\"description\" : \"Data structure of a Pet object.\"\n}" } ``` 동일한 단계를 반복하여 모델의 속성에 대한 DocumentationPart 인스턴스를 생성합니다. **참고** `MODEL` 엔터티의 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 인스턴스는 하위 리소스가 상속할 수 없습니다. ## 설명서 부분 업데이트 모든 API 엔터티 유형의 설명서 부분을 업데이트하려면 지정된 부분 식별자의 [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 인스턴스에서 PATCH 요청을 제출하여 기존 `properties` 맵을 새로운 맵으로 교체합니다. ``` PATCH /restapis/4wk1k4onj3/documentation/parts/part_id 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" : "RESOURCE_PATH", "value" : "NEW_properties_VALUE_AS_JSON_STRING" } ] } ``` 응답이 성공하면 업데이트된 `200 OK` 인스턴스를 포함한 페이로드와 함께 `DocumentationPart` 상태 코드를 반환합니다. 단일 `PATCH` 요청으로 여러 설명서 부분을 업데이트할 수 있습니다. ## 설명서 부분 나열 모든 API 엔터티 유형의 설명서 부분을 나열하려면 [DocumentationParts](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) 컬렉션에서 GET 요청을 제출합니다. ``` GET /restapis/restapi_id/documentation/parts 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 ``` 응답이 성공하면 사용 가능한 `200 OK` 인스턴스를 포함한 페이로드와 함께 `DocumentationPart` 상태 코드를 반환합니다. # 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)의 지침을 따릅니다. # 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. **가져오기**를 선택합니다. # API Gateway에서 API 설명서에 대한 액세스 제어 API 설명서를 작성 및 편집하는 전담 설명서 팀이 있는 경우 개발자(API 개발) 및 작성자 또는 편집자(콘텐츠 개발)에 대한 별도의 액세스 권한을 구성할 수 있습니다. 이는 설명서 작성에 타사 공급업체가 관련된 경우 특히 해당합니다. 설명서 팀에게 API 설명서를 생성, 업데이트 및 게시할 수 있는 액세스 권한을 부여하려면 다음 IAM 정책을 사용하여 설명서 팀에게 IAM 역할을 할당할 수 있습니다. 여기서 *account\$1id*는 설명서 팀의 AWS 계정 ID입니다. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "StmtDocPartsAddEditViewDelete", "Effect": "Allow", "Action": [ "apigateway:GET", "apigateway:PUT", "apigateway:POST", "apigateway:PATCH", "apigateway:DELETE" ], "Resource": [ "arn:aws:apigateway:us-east-1:111111111111:/restapis/*/documentation/*" ] } ] } ``` ------ API Gateway 리소스에 액세스할 수 있는 권한을 설정하는 방법에 대한 자세한 내용은 [Amazon API Gateway에서 IAM을 사용하는 방식](security_iam_service-with-iam.md) 단원을 참조하세요.