# API Gateway REST API를 사용하여 API 문서화
<a name="api-gateway-documenting-api-quick-start-with-restapi"></a>

이 단원에서는 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` 엔터티 문서화
<a name="api-gateway-documenting-api-quick-start-with-restapi-add-content-to-api"></a>

[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` 엔터티 문서화
<a name="api-gateway-documenting-api-quick-start-with-restapi-add-content-to-resource"></a>

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` 엔터티 문서화
<a name="api-gateway-documenting-api-quick-start-with-restapi-add-content-to-method"></a>

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` 엔터티 문서화
<a name="api-gateway-documenting-api-quick-start-with-restapi-add-content-to-query-parameter"></a>

요청 쿼리 파라미터에 대한 설명서를 추가하려면 `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` 엔터티 문서화
<a name="api-gateway-documenting-api-quick-start-with-restapi-add-content-to-path-parameter"></a>

경로 파라미터에 대한 설명서를 추가하려면 `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` 엔터티 문서화
<a name="api-gateway-documenting-api-quick-start-with-restapi-add-content-to-request-body"></a>

요청 본문에 대한 설명서를 추가하려면 요청 본문에 대한 [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` 엔터티 문서화
<a name="api-gateway-documenting-api-quick-start-with-restapi-add-content-to-request-header"></a>

요청 헤더에 대한 설명서를 추가하려면 요청 헤더에 대한 [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` 엔터티 문서화
<a name="api-gateway-documenting-api-quick-start-with-restapi-add-content-to-response"></a>

상태 코드의 응답에 대한 설명서를 추가하려면 해당 [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` 엔터티 문서화
<a name="api-gateway-documenting-api-quick-start-with-restapi-add-content-to-response-header"></a>

응답 헤더에 대한 설명서를 추가하려면 응답 헤더에 대한 [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` 엔터티 문서화
<a name="api-gateway-documenting-api-quick-start-with-restapi-add-content-to-authorizer"></a>

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` 엔터티 문서화
<a name="api-gateway-documenting-api-quick-start-with-restapi-add-content-to-model"></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`'의 속성이 원본 스키마의 값을 재정의합니다.

 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) 인스턴스는 하위 리소스가 상속할 수 없습니다.

## 설명서 부분 업데이트
<a name="api-gateway-documenting-api-quick-start-with-restapi-update-content"></a>

 모든 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` 요청으로 여러 설명서 부분을 업데이트할 수 있습니다.

## 설명서 부분 나열
<a name="api-gateway-documenting-api-quick-start-with-restapi-list-parts"></a>

 모든 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` 상태 코드를 반환합니다.