# 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` エンティティのドキュメントのコンテンツを更新するには、新しい `properties` マップを指定して [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\"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" }
  }
}
```

 があり、2 つの `DocumentationPart` インスタンス (1 つは `Model` 用、もう 1 つはその `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` ステータスコードが返されます。

複数のドキュメントパーツを 1 回の `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` ステータスコードが返されます。