ASP.NET Web API のヘルプ ページの作成

このチュートリアルでは、ASP.NET 4.x で ASP.NET Web API のヘルプ ページを作成する方法を示します。

Web API を作成するときは、多くの場合、ヘルプ ページを作成すると便利です。これにより、他の開発者が API の呼び出し方法を知ることができます。 すべてのドキュメントを手動で作成することもできますが、可能な限り自動生成することをお勧めします。 このタスクを簡単にするために、ASP.NET Web API には、実行時にヘルプ ページを自動生成するためのライブラリが用意されています。

API ヘルプ ページの作成

ASP.NET および Web Tools 2012.2 Update をインストールします。 この更新プログラムは、ヘルプ ページを Web API プロジェクト テンプレートに統合します。

次に、MVC 4 プロジェクト ASP.NET 新しいプロジェクトを作成し、Web API プロジェクト テンプレートを選択します。 プロジェクト テンプレートは、 ValuesControllerという名前の API コントローラーの例を作成します。 このテンプレートでは、API ヘルプ ページも作成されます。 ヘルプ ページのすべてのコード ファイルは、プロジェクトの Areas フォルダーに配置されます。

アプリケーションを実行すると、ホーム ページに API ヘルプ ページへのリンクが含まれます。 ホーム ページの相対パスは /Help です。

このリンクをクリックすると、API の概要ページが表示されます。

このページの MVC ビューは、Areas/HelpPage/Views/Help/Index.cshtml で定義されています。 このページを編集して、レイアウト、概要、タイトル、スタイルなどを変更できます。

ページのメイン部分は、コントローラー別にグループ化された API のテーブルです。 テーブル エントリは、 IApiExplorer インターフェイスを使用して動的に生成されます。 (このインターフェイスについては後で詳しく説明します)。新しい API コントローラーを追加すると、実行時にテーブルが自動的に更新されます。

"API" 列には、HTTP メソッドと相対 URI が一覧表示されます。 "Description" 列には、各 API のドキュメントが含まれています。 最初は、ドキュメントは単なるプレースホルダー テキストです。 次のセクションでは、XML コメントからドキュメントを追加する方法について説明します。

各 API には、要求本文や応答本文の例など、より詳細な情報を含むページへのリンクがあります。

既存のプロジェクトへのヘルプ ページの追加

NuGet パッケージ マネージャーを使用して、既存の Web API プロジェクトにヘルプ ページを追加できます。 このオプションは、"Web API" テンプレートとは異なるプロジェクト テンプレートから開始する場合に便利です。

[ツール] メニューの [NuGet パッケージ マネージャー] を選択し、[パッケージ マネージャー コンソール] を選択します。 [ パッケージ マネージャー コンソール ] ウィンドウで、次のいずれかのコマンドを入力します。

C# アプリケーションの場合:Install-Package Microsoft.AspNet.WebApi.HelpPage

Visual Basic アプリケーションの場合:Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

C# 用と Visual Basic 用の 2 つのパッケージがあります。 必ず、プロジェクトに一致するものを使用してください。

このコマンドは、必要なアセンブリをインストールし、(Areas/HelpPage フォルダーにある) ヘルプ ページの MVC ビューを追加します。 ヘルプ ページへのリンクを手動で追加する必要があります。 URI は /Help です。 Razor ビューでリンクを作成するには、次を追加します。

@Html.ActionLink("API", "Index", "Help", new { area = "" }, null)

また、必ず領域を登録してください。 Global.asax ファイルで、 Application_Start メソッドに次のコードを追加します (まだ存在しない場合)。

protected void Application_Start()
{
    // Add this code, if not present.
    AreaRegistration.RegisterAllAreas();

    // ...
}

API ドキュメントの追加

既定では、ヘルプ ページにはドキュメント用のプレースホルダー文字列があります。 XML ドキュメント コメントを使用して、ドキュメントを作成できます。 この機能を有効にするには、ファイル Areas/HelpPage/App_Start/HelpPageConfig.cs を開き、次の行のコメントを解除します。

config.SetDocumentationProvider(new XmlDocumentationProvider(
    HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

次に、XML ドキュメントを有効にします。 ソリューション エクスプローラーで、プロジェクトを右クリックし、[プロパティ] を選択 します。 [ ビルド ] ページを選択します。

[ 出力] で、 XML ドキュメント ファイルを確認します。 編集ボックスに、「App_Data/XmlDocument.xml」と入力します。

次に、/Controllers/ValuesController.cs で定義されている ValuesController API コントローラーのコードを開きます。 コントローラー メソッドにいくつかのドキュメント コメントを追加します。 例えば次が挙げられます。

/// <summary>
/// Gets some very important data from the server.
/// </summary>
public IEnumerable<string> Get()
{
    return new string[] { "value1", "value2" };
}

/// <summary>
/// Looks up some data by ID.
/// </summary>
/// <param name="id">The ID of the data.</param>
public string Get(int id)
{
    return "value";
}

次に、アプリケーションをもう一度ビルドして実行し、ヘルプ ページに移動します。 ドキュメント文字列は API テーブルに表示されます。

ヘルプ ページは、実行時に XML ファイルから文字列を読み取ります。 (アプリケーションをデプロイするときは、必ず XML ファイルをデプロイしてください)。

フードの下

ヘルプ ページは、Web API フレームワークの一部である ApiExplorer クラスの上に構築されています。 ApiExplorer クラスは、ヘルプ ページを作成するための原材料を提供します。 API ごとに、ApiExplorer には API を記述する ApiDescription が含まれています。 この目的のために、"API" は HTTP メソッドと相対 URI の組み合わせとして定義されます。 たとえば、次に示すのは、いくつかの異なる API です。

• GET /api/Products
• GET /api/Products/{id}
• POST /api/Products

コントローラー アクションで複数の HTTP メソッドがサポートされている場合、 ApiExplorer は各メソッドを個別の API として扱います。

ApiExplorer から API を非表示にするには、ApiExplorerSettings 属性をアクションに追加し、IgnoreApi を true に設定します。

[ApiExplorerSettings(IgnoreApi=true)]
public HttpResponseMessage Get(int id) {  }

この属性をコントローラーに追加して、コントローラー全体を除外することもできます。

ApiExplorer クラスは 、IDocumentationProvider インターフェイスからドキュメント文字列を取得します。 前に説明したように、ヘルプ ページ ライブラリには、XML ドキュメント文字列からドキュメントを取得する IDocumentationProvider が用意されています。 コードは /Areas/HelpPage/XmlDocumentationProvider.cs にあります。 独自の IDocumentationProvider を記述することで、別のソースからドキュメントを取得できます。 接続するには、HelpPageConfigurationExtensions で定義されている SetDocumentationProvider 拡張メソッドを呼び出します。

ApiExplorer は IDocumentationProvider インターフェイスを自動的に呼び出して、各 API のドキュメント文字列を取得します。 ApiDescription オブジェクトと ApiParameterDescription オブジェクトの Documentation プロパティに格納されます。

次のステップ

ここに示されているヘルプ ページに限定されるわけではありません。 実際、 ApiExplorer はヘルプ ページの作成に限定されません。 林耀皇は、あなたの視野を広げるために素晴らしいブログ記事を書いています。

• Web API ヘルプ ページへの単純なテスト クライアント ASP.NET 追加する
• ASP.NET Web API ヘルプ ページをセルフホステッド サービスで動作させる
• ASP.NET Web API のヘルプ ページ (またはクライアント) のデザイン時の生成
• 高度なヘルプ ページのカスタマイズ