ASP.NET Web API のヘルプページ自動生成パッケージを試す

ASP.NET Web API は RESTful な HTTP サービス (API) を構築するのに便利なフレームワークです。ASP.NET MVC 4 が RTW になり Web API の利用を検討されている方も多いかと思います。そんな中で、” WCF であったような API のヘルプページの自動生成機能はないのですか？” というご質問を受けることがたびたびあります。

現在のリリースでは標準でヘルプページの自動生成機能はありませんが、次期バージョンのロードマップの中では予定されています。

>> ASP.NET MVC, Web API, Web Pages ロードマップ

また、既に Web API のヘルプページ自動生成のためのパッケージがプレビュー版として NuGet で公開されていますので、こちらを使用することで、ヘルプページの自動生成を行うことができます。

★ Microsoft ASP.NET Web API Help Page (0.1.0-alpha-120814)

このパッケージを、NuGet パッケージの管理ダイアログかパッケージ マネージャー コンソールから ASP.NET Web API のプロジェクトにインストールすると、プロジェクトにヘルプページ用の Areas (エリア、区分) が追加されます。

 

そして下記のように、Areas 名（区分名）が “HelpPage” で、”Help/{action}/{apiId}” で URL ルーティングが設定されます。

HelpPageAreaRegistration.cs

 namespace DemoWebAPI.Areas.HelpPage
{
    public class HelpPageAreaRegistration : AreaRegistration
    {
        public override string AreaName
        {
            get
            {
                return "HelpPage";
            }
        }

        public override void RegisterArea(AreaRegistrationContext context)
        {
            context.MapRoute(
                "HelpPage_Default",
                "Help/{action}/{apiId} ",
                new { controller = "Help", action = "Index", apiId = UrlParameter.Optional }
            );
            HelpPageConfig.Register(GlobalConfiguration.Configuration);
        }
    }
}

Web API を実装したプロジェクトを実行して、”https://localhost:<ポート番号>/Help” を表示すると、実装されている Web API の一覧が表示され、各 API 名をクリックするとその詳細ページが表示されます。

◆ Web API 一覧ページ

◆ Web API 詳細ページ

 

もちろん、プロジェクトの HelpPage 以下のビューファイルや CSS を修正することで、ヘルプページのデザインなどを変更することができます。

まだ、次期リリースへ向けてのプレビュー版ですが、NuGet パッケージとして公開されていますので最新バージョンへの更新なども容易ですね。お試しください。