# 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 オブジェクトが自動的に stringify されます。

1. **[ドキュメントパーツの作成]** を選択します。

**[リソース]** ペインに `API` エンティティの新しいドキュメントパーツを追加するには、以下を実行します。

1. メインナビゲーションペインで、**[リソース]** を選択します。

1. **[API アクション]** メニューを選択し、**[API ドキュメントの更新]** を選択します。

      
![\[API Gateway コンソールで API エンティティのドキュメントを編集する\]](http://docs.aws.amazon.com/ja_jp/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/ja_jp/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/ja_jp/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" }
  }
}
```

 があり、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` のプロパティにより元のスキーマの値が上書きされます。

 `MODEL` エンティティの新しいドキュメントパーツを追加するには、以下を実行します。

1. メインナビゲーションペインで **[ドキュメント]** を選択し、**[ドキュメントパーツの作成]** を選択します。

1. **[ドキュメントタイプ]** には **[モデル]** を選択します。

1. **[名前]** に、モデルの名前を入力します。

1. テキストエディタに説明を入力します。

1. **[ドキュメントパーツの作成]** を選択します。リストにないモデルのドキュメントを作成できます。

1.  必要に応じて、これらのステップを繰り返し、他のモデルにドキュメントパーツを追加するか、編集します。

**[モデル]** ペインに `MODEL` エンティティの新しいドキュメントパーツを追加するには、以下を実行します。

1. ナビゲーションペインで、**[モデル]** を選択します。

1. モデルを選択し、**[ドキュメントの更新]** を選択します。

      
![\[API Gateway コンソールでモデルエンティティのドキュメントを編集する\]](http://docs.aws.amazon.com/ja_jp/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. 検索バーを使用するかオーソライザーを選択し、**[編集]** を選択します。