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

» 2013年04月23日 12時30分公開

●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")));