API Gateway コンソールを使用して API を文書化する - Amazon API Gateway
API エンティティのドキュメント化RESOURCE エンティティのドキュメント化METHOD エンティティのドキュメント化QUERY_PARAMETER エンティティのドキュメント化PATH_PARAMETER エンティティのドキュメント化REQUEST_HEADER エンティティのドキュメント化 REQUEST_BODY エンティティのドキュメント化RESPONSE エンティティのドキュメント化RESPONSE_HEADER エンティティのドキュメント化RESPONSE_BODY エンティティのドキュメント化MODEL エンティティのドキュメント化AUTHORIZER エンティティのドキュメント化

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. [編集] を選択します。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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. 検索バーを使用するかオーソライザーを選択し、[編集] を選択します。