# API Gateway 콘솔을 사용하여 API 문서화
<a name="api-gateway-documenting-api-quick-start-with-console"></a>

이 단원에서는 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` 엔터티 문서화
<a name="api-gateway-document-api-add-document-part-for-api-entity-with-console"></a>

`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` 엔터티 문서화
<a name="api-gateway-document-api-add-document-part-for-resource-entity-with-console"></a>

 `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` 엔터티 문서화
<a name="api-gateway-document-api-add-document-part-for-method-entity-with-console"></a>

 `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` 엔터티 문서화
<a name="api-gateway-document-api-add-document-part-for-request-query-entity-with-console"></a>

 `QUERY_PARAMETER` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

1. 기본 탐색 창에서 **설명서**를 선택한 다음 **설명서 부분 생성**을 선택합니다.

1. **설명서 유형**에서 **쿼리 파라미터**를 선택합니다.

1. **경로**에 경로를 입력합니다.

1. **메서드**에서 HTTP 동사를 선택합니다.

1. **이름**에 이름을 입력합니다.

1. 텍스트 편집기에서 설명을 입력합니다.

1. **설명서 부분 생성**을 선택합니다. 목록에 없는 쿼리 파라미터에 대한 설명서를 생성할 수 있습니다.

1.  필요한 경우 이 단계를 반복하여 다른 설명서 부분을 추가하거나 편집합니다.

기존 설명서 부분을 편집하려면 다음을 수행합니다.

1. **설명서** 창에서 **리소스 및 메서드** 탭을 선택합니다.

1. 쿼리 파라미터를 선택하거나 쿼리 파라미터가 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다.

1. **편집**을 선택합니다.

## `PATH_PARAMETER` 엔터티 문서화
<a name="api-gateway-document-api-add-document-part-for-path-parameter-entity-with-console"></a>

 `PATH_PARAMETER` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

1. 기본 탐색 창에서 **설명서**를 선택한 다음 **설명서 부분 생성**을 선택합니다.

1. **설명서 유형**에서 **경로 파라미터**를 선택합니다.

1. **경로**에 경로를 입력합니다.

1. **메서드**에서 HTTP 동사를 선택합니다.

1. **이름**에 이름을 입력합니다.

1. 텍스트 편집기에서 설명을 입력합니다.

1. **설명서 부분 생성**을 선택합니다. 목록에 없는 경로 파라미터에 대한 설명서를 생성할 수 있습니다.

1.  필요한 경우 이 단계를 반복하여 다른 설명서 부분을 추가하거나 편집합니다.

기존 설명서 부분을 편집하려면 다음을 수행합니다.

1. **설명서** 창에서 **리소스 및 메서드** 탭을 선택합니다.

1. 경로 파라미터를 선택하거나 경로 파라미터가 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다.

1. **편집**을 선택합니다.

## `REQUEST_HEADER` 엔터티 문서화
<a name="api-gateway-document-api-add-document-part-for-request-header-entity-with-console"></a>

 `REQUEST_HEADER` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

1. 기본 탐색 창에서 **설명서**를 선택한 다음 **설명서 부분 생성**을 선택합니다.

1. **설명서 유형**에서 **요청 헤더**를 선택합니다.

1. **경로**에 요청 헤더의 경로를 입력합니다.

1. **메서드**에서 HTTP 동사를 선택합니다.

1. **이름**에 이름을 입력합니다.

1. 텍스트 편집기에서 설명을 입력합니다.

1. **설명서 부분 생성**을 선택합니다. 목록에 없는 요청 헤더에 대한 설명서를 생성할 수 있습니다.

1.  필요한 경우 이 단계를 반복하여 다른 설명서 부분을 추가하거나 편집합니다.

기존 설명서 부분을 편집하려면 다음을 수행합니다.

1. **설명서** 창에서 **리소스 및 메서드** 탭을 선택합니다.

1. 요청 헤더를 선택하거나 요청 헤더가 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다.

1. **편집**을 선택합니다.

## `REQUEST_BODY` 엔터티 문서화
<a name="api-gateway-document-api-add-document-part-for-request-body-entity-with-console"></a>

 `REQUEST_BODY` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

1. 기본 탐색 창에서 **설명서**를 선택한 다음 **설명서 부분 생성**을 선택합니다.

1. **설명서 유형**에서 **요청 본문**을 선택합니다.

1. **경로**에 요청 본문의 경로를 입력합니다.

1. **메서드**에서 HTTP 동사를 선택합니다.

1. 텍스트 편집기에서 설명을 입력합니다.

1. **설명서 부분 생성**을 선택합니다. 목록에 없는 요청 본문에 대한 설명서를 생성할 수 있습니다.

1.  필요한 경우 이 단계를 반복하여 다른 설명서 부분을 추가하거나 편집합니다.

기존 설명서 부분을 편집하려면 다음을 수행합니다.

1. **설명서** 창에서 **리소스 및 메서드** 탭을 선택합니다.

1. 요청 본문을 선택하거나 요청 본문이 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다.

1. **편집**을 선택합니다.

## `RESPONSE` 엔터티 문서화
<a name="api-gateway-document-api-add-document-part-for-response-with-console"></a>

 `RESPONSE` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

1. 기본 탐색 창에서 **설명서**를 선택한 다음 **설명서 부분 생성**을 선택합니다.

1. **설명서 유형**에서 **응답(상태 코드)**을 선택합니다.

1. **경로**에 응답의 경로를 입력합니다.

1. **메서드**에서 HTTP 동사를 선택합니다.

1. **상태 코드**에 HTTP 상태 코드를 입력합니다.

1. 텍스트 편집기에서 설명을 입력합니다.

1. **설명서 부분 생성**을 선택합니다. 목록에 없는 응답 상태 코드에 대한 설명서를 생성할 수 있습니다.

1.  필요한 경우 이 단계를 반복하여 다른 설명서 부분을 추가하거나 편집합니다.

기존 설명서 부분을 편집하려면 다음을 수행합니다.

1. **설명서** 창에서 **리소스 및 메서드** 탭을 선택합니다.

1. 응답 상태 코드를 선택하거나 응답 상태 코드가 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다.

1. **편집**을 선택합니다.

## `RESPONSE_HEADER` 엔터티 문서화
<a name="api-gateway-document-api-add-document-part-for-response-header-entity-with-console"></a>

 `RESPONSE_HEADER` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

1. 기본 탐색 창에서 **설명서**를 선택한 다음 **설명서 부분 생성**을 선택합니다.

1. **설명서 유형**에서 **응답 헤더**를 선택합니다.

1. **경로**에 응답 헤더의 경로를 입력합니다.

1. **메서드**에서 HTTP 동사를 선택합니다.

1. **상태 코드**에 HTTP 상태 코드를 입력합니다.

1. 텍스트 편집기에서 설명을 입력합니다.

1. **설명서 부분 생성**을 선택합니다. 목록에 없는 응답 헤더에 대한 설명서를 생성할 수 있습니다.

1.  필요한 경우 이 단계를 반복하여 다른 설명서 부분을 추가하거나 편집합니다.

기존 설명서 부분을 편집하려면 다음을 수행합니다.

1. **설명서** 창에서 **리소스 및 메서드** 탭을 선택합니다.

1. 응답 헤더를 선택하거나 응답 헤더가 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다.

1. **편집**을 선택합니다.

## `RESPONSE_BODY` 엔터티 문서화
<a name="api-gateway-document-api-add-document-part-for-response-body-entity-with-console"></a>

 `RESPONSE_BODY` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

1. 기본 탐색 창에서 **설명서**를 선택한 다음 **설명서 부분 생성**을 선택합니다.

1. **설명서 유형**에서 **응답 본문**을 선택합니다.

1. **경로**에 응답 본문의 경로를 입력합니다.

1. **메서드**에서 HTTP 동사를 선택합니다.

1. **상태 코드**에 HTTP 상태 코드를 입력합니다.

1. 텍스트 편집기에서 설명을 입력합니다.

1. **설명서 부분 생성**을 선택합니다. 목록에 없는 응답 본문에 대한 설명서를 생성할 수 있습니다.

1.  필요한 경우 이 단계를 반복하여 다른 설명서 부분을 추가하거나 편집합니다.

기존 설명서 부분을 편집하려면 다음을 수행합니다.

1. **설명서** 창에서 **리소스 및 메서드** 탭을 선택합니다.

1. 응답 본문을 선택하거나 응답 본문이 포함된 리소스를 선택한 다음 검색 창을 사용하여 설명서 부분을 찾고 선택할 수 있습니다.

1. **편집**을 선택합니다.

## `MODEL` 엔터티 문서화
<a name="api-gateway-document-api-add-document-part-for-model-entity-with-console"></a>

`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` 엔터티 문서화
<a name="api-gateway-document-api-add-document-part-for-authorizer-entity-with-console"></a>

 `AUTHORIZER` 엔터티에 새 설명서 부분을 추가하려면 다음을 수행합니다.

1. 기본 탐색 창에서 **설명서**를 선택한 다음 **설명서 부분 생성**을 선택합니다.

1. **설명서 유형**에서 **권한 부여자**를 선택합니다.

1. **이름**에 권한 부여자 이름을 입력합니다.

1. 텍스트 편집기에서 설명을 입력합니다. 권한 부여자에 대한 유효한 `location` 필드의 값을 지정합니다.

1. **설명서 부분 생성**을 선택합니다. 목록에 없는 권한 부여자에 대한 설명서를 생성할 수 있습니다.

1.  필요한 경우 이 단계를 반복하여 설명서 부분을 다른 권한 부여자에 추가하거나 편집합니다.

기존 설명서 부분을 편집하려면 다음을 수행합니다.

1. **설명서** 창에서 **권한 부여자** 탭을 선택합니다.

1. 검색 창을 사용하거나 권한 부여자를 선택한 다음 **편집**을 선택합니다.