ASP.NET MVCの新機能：特集：ASP.NET 4.5新機能概説（3）（5/6 ページ）

ASP.NET 4.5新機能概説が完結。モバイル・デバイス対応、ASP.NET Web API、OAuth／OpenIDによる認証技術などのASP.NET MVC 4新機能を紹介する。

[花田善仁（監修：山田祥寛），WINGSプロジェクト]

●ASP.NET Web APIのヘルプ・ページを自動的に作成する機能［2012.2 Update］

　2012.2 Updateでは、ODataサポート機能以外にも便利な機能が追加されている。ここではWeb APIのドキュメントを自動的に生成する、ASP.NET Web API Help Pageを紹介する。

　Web APIのプロジェクト・テンプレートには、「http://ホスト名/Help」というURLにアクセスすると次のように表示されるヘルプ・ページがデフォルトで用意されている。Web APIプロジェクトを作成するとデフォルトでValuesControllerクラスが作成され、ヘルプ・ページにはこのコントローラによりAPI情報が表示される。

自動生成されたWeb APIのヘルプ・ページ

　Web APIのヘルプ・ページはコード中のドキュメントから自動的に生成されるようになっている。

　例えば、ValuesControllerクラスのGetメソッドに次のようにXMLドキュメント・コメントを記述したとしよう。

  public class ValuesController : ApiController
  {
    /// <summary>
    /// Valueのコレクションを返す
    /// </summary>
    /// <returns>文字列の配列</returns>
    public IEnumerable<string> Get()
    {
      return new string[] { "value1", "value2" };
    }

リスト7　ヘルプ・ページに表示されるドキュメント用のコメントを記述した例（ValuesController.csファイル）

　ただし、このままではヘルプ・ページには反映されない。表示するにはあと2つの手順を必要とする。

　最初に、コメントに記述した内容をXMLドキュメント・ファイルに反映させるように設定を行う。以下のようにプロジェクトのプロパティ設定ページを開き、［ビルド］−［出力］にある［XML ドキュメント ファイル］チェックボックスをチェックして、出力先のXMLドキュメント・ファイルのパスを指定する。

コメントをXMLドキュメント・ファイルに出力するように設定
この例では、出力するXMLドキュメント・ファイルとして「App_Data\ODataSample.XML」ファイルを指定している。

　次に、「Areas\HelpPage\App_Start\HelpPageConfig.cs」ファイルに、先ほど指定したXMLドキュメント・ファイルからヘルプ・ページを作成するように設定する。この設定はコメントアウトされているので、コメントを外して正しいXMLドキュメント・ファイルへのパスを指定する。

public static class HelpPageConfig
{
  public static void Register(HttpConfiguration config)
  {
    //// Uncomment the following to use the documentation from XML documentation file.
    config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/¥ODataSample.XML")));

リスト8　XMLドキュメント・ファイルのパスを指定する例（HelpPageConfig.csファイル）

　プロジェクトをビルドして再度実行し、ヘルプ・ページを参照すると、コメントに書かれた内容が反映されているのが確認できる（次の画面を参照）。

コメントが反映されたWeb APIヘルプ・ページ