API Gateway コンソールを使用して API を文書化する - Amazon API Gateway

API Gateway コンソールを使用して API を文書化する

このセクションでは、API Gateway コンソールを使用して API のドキュメントパートを作成および維持する方法について説明します。

API のドキュメントを作成および編集するための前提条件は、すでに API を作成していることです。このセクションでは、例として PetStore API を使用します。API Gateway コンソールを使用して API を作成するには、「チュートリアル: サンプルをインポートして REST API を作成する」の手順に従います。

API エンティティのドキュメント化

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

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

  2. [ドキュメントタイプ] には [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 されます。

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

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

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

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

    
                      API Gateway コンソールで API エンティティのドキュメントを編集する

既存のドキュメントパーツを編集するには、以下を実行します。

  1. [ドキュメント] ペインで、[リソースとメソッド] タブを選択します。

  2. API の名前を選択し、API カードで [編集] を選択します。

RESOURCE エンティティのドキュメント化

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

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

  2. [ドキュメントタイプ] には [リソース] を選択します。

  3. [パス] にはパスを入力します。

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

    { "description": "The PetStore's root resource." }
  5. [ドキュメントパーツの作成] を選択します。リストにないリソースのドキュメントを作成できます。

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

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

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

  2. リソースを選択し、[ドキュメントの更新] を選択します。

    
                        API Gateway コンソールでリソースエンティティのドキュメントを編集する

既存のドキュメントパーツを編集するには、以下を実行します。

  1. [ドキュメント] ペインで、[リソースとメソッド] タブを選択します。

  2. ドキュメントパーツを含むリソースを選択し、[編集] を選択します。

METHOD エンティティのドキュメント化

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

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

  2. [ドキュメントタイプ] には [メソッド] を選択します。

  3. [パス] にはパスを入力します。

  4. [メソッド] で、HTTP 動詞を選択します。

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

    { "tags" : [ "pets" ], "summary" : "List all pets" }
  6. [ドキュメントパーツの作成] を選択します。リストにないメソッドのドキュメントを作成できます。

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

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

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

  2. メソッドを選択し、[ドキュメントの更新] を選択します。

    
                        API Gateway コンソールでメソッドエンティティのドキュメントを編集する

既存のドキュメントパーツを編集するには、以下を実行します。

  1. [ドキュメント] ペインで、[リソースとメソッド] タブを選択します。

  2. メソッドを選択するか、メソッドを含むリソースを選択してから、検索バーを使用してドキュメントパーツを検索および選択できます。

  3. [Edit] (編集) を選択します。

QUERY_PARAMETER エンティティのドキュメント化

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

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

  2. [ドキュメントタイプ] には [クエリパラメータ] を選択します。

  3. [パス] にはパスを入力します。

  4. [メソッド] で、HTTP 動詞を選択します。

  5. [ロール名] に名前を入力します。

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

  7. [ドキュメントパーツの作成] を選択します。リストにないクエリパラメータのドキュメントを作成できます。

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

既存のドキュメントパーツを編集するには、以下を実行します。

  1. [ドキュメント] ペインで、[リソースとメソッド] タブを選択します。

  2. クエリパラメータを選択するか、クエリパラメータを含むリソースを選択してから、検索バーを使用してドキュメントパーツを検索および選択できます。

  3. [Edit] (編集) を選択します。

PATH_PARAMETER エンティティのドキュメント化

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

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

  2. [ドキュメントタイプ] には [パスパラメータ] を選択します。

  3. [パス] にはパスを入力します。

  4. [メソッド] で、HTTP 動詞を選択します。

  5. [ロール名] に名前を入力します。

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

  7. [ドキュメントパーツの作成] を選択します。リストにないパスパラメータのドキュメントを作成できます。

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

既存のドキュメントパーツを編集するには、以下を実行します。

  1. [ドキュメント] ペインで、[リソースとメソッド] タブを選択します。

  2. パスパラメータを選択するか、パスパラメータを含むリソースを選択してから、検索バーを使用してドキュメントパーツを検索および選択できます。

  3. [Edit] (編集) を選択します。

REQUEST_HEADER エンティティのドキュメント化

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

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

  2. [ドキュメントタイプ] には [リクエストヘッダー] を選択します。

  3. [パス] には、リクエストヘッダーのパスを入力します。

  4. [メソッド] で、HTTP 動詞を選択します。

  5. [ロール名] に名前を入力します。

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

  7. [ドキュメントパーツの作成] を選択します。リストにないリクエストヘッダーのドキュメントを作成できます。

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

既存のドキュメントパーツを編集するには、以下を実行します。

  1. [ドキュメント] ペインで、[リソースとメソッド] タブを選択します。

  2. リクエストヘッダーを選択するか、リクエストヘッダーを含むリソースを選択してから、検索バーを使用してドキュメントパーツを検索および選択できます。

  3. [Edit] (編集) を選択します。

REQUEST_BODY エンティティのドキュメント化

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

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

  2. [ドキュメントタイプ] には [リクエスト本文] を選択します。

  3. [パス] には、リクエスト本文のパスを入力します。

  4. [メソッド] で、HTTP 動詞を選択します。

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

  6. [ドキュメントパーツの作成] を選択します。リストにないリクエスト本文のドキュメントを作成できます。

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

既存のドキュメントパーツを編集するには、以下を実行します。

  1. [ドキュメント] ペインで、[リソースとメソッド] タブを選択します。

  2. リクエスト本文を選択するか、リクエスト本文を含むリソースを選択してから、検索バーを使用してドキュメントパーツを検索および選択できます。

  3. [Edit] (編集) を選択します。

RESPONSE エンティティのドキュメント化

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

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

  2. [ドキュメントタイプ] には、[レスポンス (ステータスコード)] を選択します。

  3. [パス] には、レスポンスのパスを入力します。

  4. [メソッド] で、HTTP 動詞を選択します。

  5. [ステータスコード] には、HTTP ステータスコードを入力します。

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

  7. [ドキュメントパーツの作成] を選択します。リストにないレスポンスステータスコードのドキュメントを作成できます。

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

既存のドキュメントパーツを編集するには、以下を実行します。

  1. [ドキュメント] ペインで、[リソースとメソッド] タブを選択します。

  2. レスポンスステータスコードを選択するか、レスポンスステータスコードを含むリソースを選択してから、検索バーを使用してドキュメントパーツを検索および選択できます。

  3. [Edit] (編集) を選択します。

RESPONSE_HEADER エンティティのドキュメント化

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

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

  2. [ドキュメントタイプ] には [レスポンスヘッダー] を選択します。

  3. [パス] には、レスポンスヘッダーのパスを入力します。

  4. [メソッド] で、HTTP 動詞を選択します。

  5. [ステータスコード] には、HTTP ステータスコードを入力します。

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

  7. [ドキュメントパーツの作成] を選択します。リストにないレスポンスヘッダーのドキュメントを作成できます。

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

既存のドキュメントパーツを編集するには、以下を実行します。

  1. [ドキュメント] ペインで、[リソースとメソッド] タブを選択します。

  2. レスポンスヘッダーを選択するか、レスポンスヘッダーを含むリソースを選択してから、検索バーを使用してドキュメントパーツを検索および選択できます。

  3. [Edit] (編集) を選択します。

RESPONSE_BODY エンティティのドキュメント化

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

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

  2. [ドキュメントタイプ] には [レスポンス本文] を選択します。

  3. [パス] には、レスポンス本文のパスを入力します。

  4. [メソッド] で、HTTP 動詞を選択します。

  5. [ステータスコード] には、HTTP ステータスコードを入力します。

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

  7. [ドキュメントパーツの作成] を選択します。リストにないレスポンス本文のドキュメントを作成できます。

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

既存のドキュメントパーツを編集するには、以下を実行します。

  1. [ドキュメント] ペインで、[リソースとメソッド] タブを選択します。

  2. レスポンス本文を選択するか、レスポンス本文を含むリソースを選択してから、検索バーを使用してドキュメントパーツを検索および選択できます。

  3. [Edit] (編集) を選択します。

MODEL エンティティのドキュメント化

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. メインナビゲーションペインで [ドキュメント] を選択し、[ドキュメントパーツの作成] を選択します。

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

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

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

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

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

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

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

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

    
                        API Gateway コンソールでモデルエンティティのドキュメントを編集する

既存のドキュメントパーツを編集するには、以下を実行します。

  1. [ドキュメント] ペインで [モデル] タブを選択します。

  2. 検索バーを使用するかモデルを選択し、[編集] を選択します。

AUTHORIZER エンティティのドキュメント化

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

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

  2. [ドキュメントタイプ] には [オーソライザー] を選択します。

  3. [名前] に、オーソライザーの名前を入力します。

  4. テキストエディタに説明を入力します。オーソライザーの有効な [location] フィールドで値を指定します。

  5. [ドキュメントパーツの作成] を選択します。リストにないオーソライザーのドキュメントを作成できます。

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

既存のドキュメントパーツを編集するには、以下を実行します。

  1. [ドキュメント] ペインで [オーソライザー] タブを選択します。

  2. 検索バーを使用するかオーソライザーを選択し、[編集] を選択します。