arp4ra
Last Updated: August 21, 2018
·
6
· STK

3ステップでWebAPIドキュメントを作る方法

Microsoft.AspNet.WebApi.HelpPageのAPIヘルプページにはドキュメント作成に関する情報はありません。下記のようにAPI Controllerアクションで使えるドキュメントはありません。

ドキュメント化を有効化するには、下記の簡単なステップを踏めば直ぐに対応できます。

Step1- コントローラーレベル

テスト目的で、 DocumentationsControllerという名前で新しいApiControllerを作成します。

 public class DocumentationsController : ApiController
{
    // GET api/documentation
    public IEnumerable<string> Get()
    {
        return new string[] { "value1", "value2" };
    }
....

ドキュメント化をする対象となるコントローラーアクションの前に///を入れます。

// GET api/documentation
/// <summary>
/// This is how we create a documentation
/// </summary>
/// <returns></returns>
public IEnumerable<string> Get()
....

なにがドキュメント化されたか確認するには、”<”を打つとIntelliSenseが表示されるか、[https://msdn.microsoft.com/en-us/library/b2s063f7.aspx,(]MSDN page.)に飛ばされます。

Step2- プロパティの作成

プロジェクトプロパティページを開き、ドキュメント化するためにxmlアウチプットの設定をします。この例では、ドキュメンテーションファイルは App_Data\Documentation.XML.のようになります。

Step3 - ヘルプページの設定

ドキュメンテーションのxmlファイルを使うためのHelpPageConfigの設定は、~\Areas\HelpPage\HelpPageConfig.cs.にて行います。

デフォルト設定で、config.SetDocumentationProviderステ0トメントはコメントアウトされています。このステートメントを用い、ローカルのDocumentationProviderを指定します。

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/Documentation.xml")));

APIドキュメントのページをリロードすると:

ドキュメントファイルの作成ができました。

これにて完了です。