メニュー
Amazon API Gateway
開発者ガイド

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

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

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

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

API エンティティのドキュメントパーツを追加するには、PetStore API から [Resources] を選択します。[Actions → Edit API Documentation] メニュー項目を選択します。

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

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

Copy
{ "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 エンティティのドキュメントプロパティマップの表示

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

または、メインナビゲーションペインから [PetStore] API で [Documentation] を選択します。[Type 」 で [Path Parameter] を選択します。リストからパスパラメーターの [Edit] を選択します。コンテンツを変更して、[Save] を選択します。

リストされていないパスパラメーターを追加するには、[Create Documentation Part] を選択します。[Type] で [Path Parameter] を選択します。[Path] でリソースパスを設定し、[Method] からメソッドを選択して、[Name] でパスパラメーター名を設定します。ドキュメントのプロパティを追加し、[Save] を選択します。

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

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

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

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

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

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

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

または、メインナビゲーションペインから API で [Documentation] を選択します。次に、[Type] として Request Body を選択します。リストされたリクエスト本文で [Edit] を選択し、ドキュメントを変更します。リストされていないリクエスト本文のドキュメントを追加するには、[Create Documentation Part] を選択します。[Type 」 で [Request Body] を選択します。[Path] でリソースパスを設定します。[Method] の HTTP 動詞を選択します。次に、properties マップを追加および保存します。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

MODEL エンティティをドキュメント化するには、モデルの DocumentPart インスタンスと、モデルの各 properties' を作成および管理する必要があります。たとえば、各 API に付属する Error モデルには、デフォルトでスキーマ定義

Copy
{ "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "Error Schema", "type" : "object", "properties" : { "message" : { "type" : "string" } } }

があり、2 つの DocumentationPart インスタンス (1 つは Model 用、もう 1 つはその message プロパティ用) が必要です。

Copy
{ "location": { "type": "MODEL", "name": "Error" }, "properties": { "title": "Error Schema", "description": "A description of the Error model" } }

および

Copy
{ "location": { "type": "MODEL", "name": "Error.message" }, "properties": { "description": "An error message." } }

API がエクスポートされると、DocumentationPart のプロパティにより元のスキーマの値が上書きされます。

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

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

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

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

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

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

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

オーソライザーのドキュメントパーツを追加するには、[Create Documentation Part] を選択します。[Type] で [Authorizer] を選択します。オーソライザーの [Name] の有効な location フィールドに値を指定します。

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

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