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

  • [アーティクル]

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

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

Screenshot of the A S P dot NET A P I help page, showing the available A P I products to select from and their descriptions.

API ヘルプ ページの作成

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

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

Screenshot of the Web A P I project template's menu options, circling the area and help page folders.

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

Screenshot of the home page, pointing to the A P I clickable letters that will open the link to the help page.

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

Screenshot of the A P I summary help page, showing the different A P I values and their description.

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

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

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

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

Screenshot of one of the A P I selection values, showing the response information and response body formats.

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

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 ドキュメントを有効にします。 ソリューション エクスプローラーで、プロジェクトを右クリックして [プロパティ] を選択します。 [ビルド] ページを選択します。

Screenshot of the project's drop-down menu in the solution explorer window, highlighting the build option.

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

Screenshot of the Output dialog box, showing the output path and the option to select the X M L documentation file.

次に、/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";
}

Note

ヒント: メソッドの上の行にキャレットを配置し、3 つのスラッシュを入力すると、Visual Studio によって XML 要素が自動的に挿入されます。 その後、空白を入力できます。

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

Screenshot of the A P I table in the help pages, showing the documentation string in the A P I value and description.

ヘルプ ページは、実行時に 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 はヘルプ ページの作成に限定されません。 Yao Huang Lin は、既成概念にとらわれずに考えるきっかけとなる素晴らしいブログ記事をいくつか書いています。