WebAPIのヘルプページを簡単に公開する方法

WebAPIを作成したものの、そのインターフェース仕様をドキュメント化するのってまぁまぁ面倒だと思います*1。

そんな時にWebAPIを公開しているサイトにAPIのヘルプを自動生成して公開する方法があるので紹介します。

Microsoft.AspNet.WebApi.HelpPageのインストール

Microsoft.AspNet.WebApi.HelpPageというパッケージがNuGetで公開されていますのでこれをインストールします。

• NuGet Gallery | Microsoft ASP.NET Web API 2.1 Help Page 5.1.2

パッケージマネージャコンソールからインストールする場合は以下のコマンドで行います。

Install-Package Microsoft.AspNet.WebApi.HelpPage

これでWebサイトを実行して、[サイトのURL]/Helpにアクセスすると、自動で以下のようなヘルプページを見ることができるようになっています。

ただ、APIの説明が「No documentation available.」になってたりして、ヘルプの役割を十分には果たせていません。

そこで、移行の手順でクラスやメソッドのコメントをヘルプに反映するようにします。

HelpPageConfig.csの修正

\Areas\HelpPage\App_Start\HelpPageConfig.cs を開き、Registerメソッドにある下記部分のコメントを外します。

//// Uncomment the following to use the documentation from XML documentation file.
//config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

プロジェクトの設定

プロジェクトのプロパティを開き、以下のようにビルド時にXMLドキュメントファイルを出力するよう設定します。

出力先はHelpPageConfig.csに書かれているパスに合わせておきます。

コントローラのコメント

以下のようにコントローラクラスやそのメソッドにコメントを書いておきます。

ちなみに、コメント入れたい箇所で「///」と入力してEnterを押すとコメントのひな形が作成されます。

/// <summary>
/// 受付時の集金額計算API
/// </summary>
public class FeeController : ApiController
{
    private MyDbContext db = new MyDbContext();

    /// <summary>
    /// 条件から集金額を計算する
    /// </summary>
    /// <param name="id">勉強会ID</param>
    /// <param name="attendSocialGathering">懇親会参加（true/false）</param>
    /// <param name="isStudent">学生（true/false）</param>
    /// <param name="isInstructor">講師（true/false）</param>
    /// <param name="isConcerned">会場関係者（true/false）</param>
    /// <param name="isStaff">勉強会スタッフ（true/false）</param>
    /// <returns></returns>
    public FeeInfo Get(int id, bool attendSocialGathering, bool isStudent, bool isInstructor, bool isConcerned, bool isStaff)
    {
        /// 省略
    }

実行結果

先ほどのヘルプページを見ると以下のようにコメントに書いた内容が反映されています。

APIのパラメータについても以下のように反映されています。

ちなみにこのヘルプですが、もちろんレスポンスの形式も出力してくれますが、加えて例も出力してくれます。便利ですね。

*1:本来なら先にドキュメントがあるべきなのかもしれませんが…