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

特集:ASP.NET 4.5新機能概説(3):ASP.NET MVCの新機能 (5/6)

[花田善仁(監修:山田祥寛),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のヘルプ・ページ

 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ドキュメント・ファイルに出力するように設定
この例では、出力する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ヘルプ・ページ コメントが反映されたWeb APIヘルプ・ページ

Copyright© Digital Advantage Corp. All Rights Reserved.

編集部からのお知らせ

RSSについて

アイティメディアIDについて

メールマガジン登録

@ITのメールマガジンは、 もちろん、すべて無料です。ぜひメールマガジンをご購読ください。