読者です 読者をやめる 読者になる 読者になる

miso_soup3 Blog

主に ASP.NET 関連について書いています。

Hokuriku.NET vol.11, ASP.NET WEB API ヘルプページ補足

2013/01/26(日)に富山で開催された Hokuriku.NET vol.11 に参加してきました。
全国各地、遠いところから足を運んで下さった皆様、
素晴らしいセッションをして頂いたスピーカーの方々、
そしてスタッフの皆様、本当にありがとうございました。

ぶりしゃぶも大変美味しかったです。
富山でぶりしゃぶが食べられるところは、今回お世話になったお店「酒菜工房 だい」の他に、
だい人、ひみ浜、醸家 などがあります。(他、おすすめがありましたら教えて下さい。)
あと、「ぶりしゃぶ レシピ」でBingると、お家でも楽しめます。

LT

今回、地元枠に甘えて、LTをさせて頂きました。
ASP.NET WEB API の紹介です。


このLTの中で挙げたヘルプページについて、
3点、補足しておきます。

  • 1.ヘルプページに、ドキュメントコメントをのせる
  • 2.ヘルプページ Azure Web Site への発行時の注意
  • 3.ヘルプページ上でのデバッグ方法

※対象バージョンは、
Microsoft ASP.NET Web API Help Page 0.3.0-rc
A Simple Test Client for ASP.NET Web API 0.0.4-alpha
です。

1.ヘルプページに、ドキュメントコメントをのせる

NuGet からヘルプページのパッケージである「Microsoft.AspNet.WebApi.HelpPage -Pre」をインストールし、
そのまま実行すると、ヘルプページには下のように表示されます。

右側に「Documentation for "GET"」と表示されていますが、
この場所に、API のメソッドのドキュメントコメントを
表示させることができるようになっています。
その方法を記載します。

ドキュメントコメントの追加

ApiController のアクションメソッドに、ドキュメントコメントを追加します。

ヘルプページの設定

~/Areas/HelpPage/App_Start/HelpPageConfig.cs の中の
下のコードをコメントアウトします。
このコードは、App_Data フォルダにある XmlDocument.xml からドキュメントコメントを参照するという意図のコードです。

ドキュメントコメント XML 生成

ドキュメントコメントの XML ファイルを生成するように設定します。
WEB API プロジェクトのプロパティから、「ビルド」タブを開き、
下のように、「出力」の「XML ドキュメントファイル」にチェックをいれ、
「App_Data/XmlDocument.xml」を入力します。

この「App_Data/XmlDocument.xml」は、先ほどのコード「~/App_Data/XmlDocument.xml」と対応しています。

以上の操作で、下のように
ドキュメントコメントがヘルプページに表示されるようになります。

2.ヘルプページ Azure Web Site への発行時の注意

上記の設定後に、Azure Web Site へ発行するときは、1つ操作が必要です。

App_Data/XmlDocument.xml を、プロジェクトに含めてから
発行する必要があります。


(XmlDocument.xml が表示されない場合は、「すべてのファイルを表示」で表示させます。)

3.ヘルプページ上でのデバッグ方法

ヘルプページ上での API デバッグは、
NuGet の「WebApiTestClient -Pre」パッケージをインストールすると便利です。

インストール後、
~/Areas/HelpPage/Views/Help/Api.cshtml に、
下の2行を追加します。
@Html.DisplayForModel("TestClientDialogs")
@Html.DisplayForModel("TestClientReferences")

以上で、APIデバッグを実行できるようになります。

もし実行できない場合は、
Areas/HelpPage/Views/Help/DisplayTemplates/TestClientReferences.cshtml の中の
Script 参照を確認してみて下さい。

おしまい

ちなみに ASP.NET Fall 2012 Update Preview では、
WEB API プロジェクトの中にすでにヘルプページが追加されています。
いろいろカスタマイズのノウハウが必要になりそうだなーと思いました。