Amazon API Gateway
開発者ガイド

API Gateway コンソールを使用した API のドキュメント化

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

API のドキュメントを作成および編集するための前提条件は、すでに API を作成していることです。このセクションでは、例として PetStore を使用します。API Gateway コンソールを使用して API を作成するには、「例から API Gateway API を構築する」の手順に従ってください。

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

API エンティティのドキュメントパーツを追加するには、PetStore API から [リソース] を選択します。[アクション] - [API ドキュメントの編集] メニュー項目を選択します。


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

API のドキュメントパーツが作成されなかった場合、ドキュメントパーツの properties マップエディターを取得します。テキストエディターに次の properties マップを入力し、[保存] を選択してドキュメントパーツを作成します。

{ "info": { "description": "Your first API Gateway API.", "contact": { "name": "John Doe", "email": "john.doe@api.com" } } }

注記

properties マップは JSON 文字列にエンコードしません。API Gateway REST API を使用する際に行う必要があるためです。API Gateway コンソールにより、JSON オブジェクトが自動的に stringify されます。


                            API Gateway コンソールでの API エンティティのドキュメントプロパティマップの編集

ドキュメントパーツがすでに作成されている場合、次に示すようにまず properties マップビューワーを取得します。


                            API Gateway コンソールでの API エンティティのドキュメントプロパティマップの表示

[編集] を選択すると、前に示したように properties マップエディターが表示されます。

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

API のルートリーソースのドキュメントパーツを追加または編集するには、[リソース] ツリーで [/] を選択し、[アクション → リソースドキュメントの編集] メニュー項目を選択します。

このエンティティのドキュメントパーツが作成されなかった場合、[ドキュメント] ウィンドウを取得します。エディターに有効な properties マップを入力します。次に、[保存] と [閉じる] を選択します。

{ "description": "The PetStore's root resource." }

RESOURCE エンティティのドキュメントパーツがすでに定義されている場合、ドキュメントビューワーを取得します。[編集] を選択して [ドキュメント] エディターを開きます。既存の properties マップを変更します。[保存] を選択し、[閉じる] を選択します。

必要に応じて、これらのステップを繰り返してドキュメントパーツを他の RESOURCE エンティティに追加します。

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

METHOD エンティティのドキュメントを追加または編集するには、ルートリソースの GET メソッドを例として使用し、[/] リソースで [GET] を選択して [アクション → メソッドドキュメントの編集] メニュー項目を選択

新しいドキュメントパーツの場合、[ドキュメント] ウィンドウで [ドキュメント] エディターに次の properties マップを入力します。次に、[保存] と [閉じる] を選択します。

{ "tags" : [ "pets" ], "description" : "PetStore HTML web page containing API usage information" }

既存のドキュメントの場合、[ドキュメント] ビューワーから [編集] を選択します。[ドキュメント] エディターでドキュメントコンテンツを編集し、[保存] を選択します。[Close] を選択します。

[ドキュメント] ビューワーからは、ドキュメントパーツを削除することもできます。

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

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

リクエストクエリパラメータのドキュメントパーツを追加または編集するには、GET /pets?type=...&page=... メソッドを例として使用し、[リソース] ツリーから [/pets] で [GET] を選択します。[メソッドの実行] ウィンドウで [メソッドリクエスト] を選択します。[URL クエリ文字列パラメータ] セクションを展開します。[ページ] クエリパラメータを選択し、たとえば書籍のアイコンを選択して [ドキュメント] ビューワーまたはエディターを開きます。


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

または、メインナビゲーションペインから [PetStore] API で [ドキュメント] を選択できます。次に、[タイプ] として Query Parameter を選択します。PetStore サンプル API の場合、これにより page および type クエリパラメータのドキュメントパーツが表示されます。


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

他のメソッドに定義されたクエリパラメータを持つ API の場合、[パス] に影響を受けるリソースの path を指定する、[メソッド] から目的の HTTP メソッドを選択する、または [名前] にクエリパラメータ名を入力することにより、選択内容をフィルタリングできます。

たとえば、page クエリパラメータを選択します。[編集] を選択して、既存のドキュメントを編集します。[保存] を選択して変更を保存します。

QUERY_PARAMETER エンティティの新しいドキュメントパーツを追加するには、[ドキュメントパーツの作成] を選択します。[タイプ] で [Query Parameter] を選択します。[パス] にリソースパス (/pets など) を入力します。[メソッド] で HTTP 動詞 (GET など) を選択します。テキストエディターに properties と入力します。次に、[Save ] を選択します。

必要に応じて、これらのステップを繰り返して、他のリクエストクエリパラメーターにドキュメントパーツを追加します。

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

パスパラメータのドキュメントを追加または編集するには、パスパラメータにより指定されたリソースでメソッドの [メソッドリクエスト] に移動します。[リクエストパス] セクションを展開します。パスパラメータの書籍のアイコンを選択し、[ドキュメント] ビューワーまたはエディターを開きます。ドキュメントパーツのプロパティを追加または変更します。

または、メインナビゲーションペインから [PetStore] API で [ドキュメント] を選択します。[タイプ] で [Path Parameter] を選択します。リストからパスパラメータの [編集] を選択します。コンテンツを変更して、[保存] を選択します。

リストされていないパスパラメータを追加するには、[ドキュメントパーツの作成] を選択します。[タイプ] で [パスパラメータ] を選択します。[パス] でリソースパスを設定し、[メソッド] からメソッドを選択して、[名前] でパスパラメータ名を設定します。ドキュメントのプロパティを追加し、[保存] を選択します。

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

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

リクエストヘッダーのドキュメントを追加または編集するには、ヘッダーパラメータを含むメソッドの [メソッドリクエスト] に移動します。[HTTP リクエストヘッダー] セクションを展開します。ヘッダーの書籍のアイコンを選択し、[ドキュメント] ビューワーまたはエディターを開きます。ドキュメントパーツのプロパティを追加または変更します。

または、メインナビゲーションペインから API で [ドキュメント] を選択します。次に、[タイプ] として Request Header を選択します。リストされたリクエストヘッダーで [編集] を選択し、ドキュメントを変更します。リストされていないリクエストヘッダーのドキュメントを追加するには、[ドキュメントパーツの作成] を選択します。[タイプ] で [リクエストヘッダー] を選択します。[パス] でリソースパスを指定します。[メソッド] のメソッドを選択します。[名前] でヘッダー名を入力します。次に、properties マップを追加および保存します。

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

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

リクエストボディのドキュメントを追加または編集するには、メソッドの [メソッドリクエスト] に移動します。[リクエストボディ] の書籍のアイコンを選択し、[ドキュメント] ビューワーを開いた後、エディターを開きます。ドキュメントパーツのプロパティを追加または変更します。

または、メインナビゲーションペインから API で [ドキュメント] を選択します。次に、[タイプ] として Request Body を選択します。リストされたリクエストボディで [編集] を選択し、ドキュメントを変更します。リストされていないリクエストボディのドキュメントを追加するには、[ドキュメントパーツの作成] を選択します。[タイプ] で [Request Body] を選択します。[パス] でリソースパスを設定します。[メソッド] の HTTP 動詞を選択します。次に、properties マップを追加および保存します。

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

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

レスポンスのドキュメントを追加または編集するには、メソッドの [メソッドレスポンス] に移動します。[メソッドレスポンス] の書籍のアイコンを選択し、[ドキュメント] ビューワーを開いた後、エディターを開きます。ドキュメントパーツのプロパティを追加または変更します。


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

または、メインナビゲーションペインから API で [ドキュメント] を選択します。次に、[タイプ] として Response (status code) を選択します。指定された HTTP ステータスコードのリストされたレスポンスで [編集] を選択し、ドキュメントを変更します。リストされていないレスポンス本文のドキュメントを追加するには、[ドキュメントパーツの作成] を選択します。[タイプ] で [レスポンス (ステータスコード)] を選択します。[パス] でリソースパスを設定します。[メソッド] の HTTP 動詞を選択します。[ステータスコード] に HTTP ステータスコードを入力します。次に、ドキュメントパーツのプロパティを追加して保管します。

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

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

レスポンスヘッダーのドキュメントを追加または編集するには、メソッドの [メソッドレスポンス] に移動します。特定の HTTP ステータスのレスポンスセクションを展開します。[StatusCode のレスポンスヘッダー] でレスポンスヘッダーの書籍のアイコンを選択し、[ドキュメント] ビューワーおよびエディターを開きます。ドキュメントパーツのプロパティを追加または変更します。

または、メインナビゲーションペインから API で [ドキュメント] を選択します。次に、[タイプ] として Response Header を選択します。リストされたレスポンスヘッダーで [編集] を選択し、ドキュメントを変更します。リストされていないレスポンスヘッダーのドキュメントを追加するには、[ドキュメントパーツの作成] を選択します。[タイプ] で [レスポンスヘッダー] を選択します。[パス] でリソースパスを設定します。[メソッド] の HTTP 動詞を選択します。[ステータスコード] に HTTP ステータスコードを入力します。[名前] にレスポンスヘッダー名を入力します。次に、ドキュメントパーツのプロパティを追加して保管します。

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

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

レスポンス本文のドキュメントを追加または編集するには、メソッドの [メソッドレスポンス] に移動します。特定の HTTP ステータスのレスポンスセクションを展開します。[StatusCode のレスポンスボディ] の書籍のアイコンを選択し、[ドキュメント] ビューワーおよびエディターを開きます。ドキュメントパーツのプロパティを追加または変更します。

または、メインナビゲーションペインから API で [ドキュメント] を選択します。次に、[タイプ] として Response Body を選択します。リストされたレスポンス本文で [編集] を選択し、ドキュメントを変更します。リストされていないレスポンス本文のドキュメントを追加するには、[ドキュメントパーツの作成] を選択します。[タイプ] で [レスポンス本文] を選択します。[パス] でリソースパスを設定します。[メソッド] の HTTP 動詞を選択します。[ステータスコード] に HTTP ステータスコードを入力します。次に、ドキュメントパーツのプロパティを追加して保管します。

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

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

モデルのドキュメントを追加するには、メインナビゲーションペインで API の [モデル] に移動します。リストされたモデルの名前にある書籍のアイコンを選択し、[ドキュメント] ビューワーおよびエディターを開きます。ドキュメントパーツのプロパティを追加または変更します。

または、メインナビゲーションペインから API で [ドキュメント] を選択します。次に、[タイプ] として Model を選択します。リストされたモデルで [編集] を選択し、ドキュメントを変更します。リストされていないモデルのドキュメントを追加するには、[ドキュメントパーツの作成] を選択します。[タイプ] で [モデル] を選択します。[名前] でモデルに名前を付けます。次に、ドキュメントパーツのプロパティを追加して保管します。

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

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

オーソライザーのドキュメントを追加または編集するには、メインナビゲーションペインで API の [オーソライザー] に移動します。リストされたオーソライザーの書籍のアイコンを選択し、[ドキュメント] ビューワーを開いた後、エディターを開きます。ドキュメントパーツのプロパティを追加または変更します。

または、メインナビゲーションペインから API で [ドキュメント] を選択します。次に、[タイプ] として Authorizer を選択します。リストされたオーソライザーで [編集] を選択し、ドキュメントを変更します。リストされていないオーソライザーのドキュメントを追加するには、[ドキュメントパーツの作成] を選択します。[タイプ] で [オーソライザー] を選択します。[名前] でオーソライザーに名前を付けます。次に、ドキュメントパーツのプロパティを追加して保管します。

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

オーソライザーのドキュメントパーツを追加するには、[ドキュメントパーツの作成] を選択します。[タイプ] で [オーソライザー] を選択します。オーソライザーの [名前] の有効な location フィールドに値を指定します。

properties マップエディタでドキュメントのコンテンツを追加し、保存します。

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