ASP.NET MVC 4 WebApi Help Page 建立自訂的說明文件

在建立 ASP.NET MVC 4 WebApi 專案，過程中它會建立一個 Help Page，協助開發人員對自己撰寫的 Controller 下註解，以便初次進入專案的開發人員快速了解每一個 Api 並且使用，且方便交接。

看這次的例子，此 Controller 有兩個 Api，如下圖所示：

看來此處的 Api 說明，並不是開發人員自己定義的，所以接下來的設定，可以使這些說明變成是開發人員定義的。

參考：Creating Help Pages for ASP.NET Web API

1.

在專案的 Areas 下有 Help Page 資料夾，這裡就是產生 Help Page 內容的 MVC，如有興趣可參考。 接著就把 App_Start 底下檔案 HelpPageConfig.cs 做修改：

config.SetDocumentationProvider(new XmlDocumentationProvider(
    HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

把此行註解拿掉以啟用，此行意思是建立一個 XML 檔案來存放開發人員定義的說明文件，存放位置為 ~/App_Data/XmlDocument.xml。

2.

此時對專案點擊右鍵 > 屬性 > 建置，對 XML 文件檔案方框打勾，設定存放位置為 App_Data/XmlDocument.xml。

3.

再去修改剛剛的 Controller Api，使用三個斜線的註解去說明此 Api 的功能為何，如以下所示：

/// <summary>
/// [後台] 取得 單一部門 資料
/// </summary>
/// <param name="id">編號</param>
/// <param name="language">語系</param>
/// <param name="date">日期</param>
/// <returns></returns>
public async Task<OM_Department> Get(Guid id, string language, DateTime date)
{
 // ...
}

設定到此，已經算是完成了。最後執行專案看看結果：

而 App_Data/XmlDocument.xml 產生的內容為：

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>Backend</name>
    </assembly>
    <members>
 
  ...
  
        <member name="M:Backend.Areas.orgmaintainer.Controllers.OM_DepartmentController.Get(System.Guid,System.String,System.DateTime)">
            <summary>
            [後台] 取得 單一部門 資料
            </summary>
            <param name="id">編號</param>
            <param name="language">語系</param>
            <param name="date">日期</param>
            <returns></returns>
        </member>
        
  ...
  
    </members>
</doc>

最後補充一點，必須每個 Api 上都要加上註解以說明，不然它是不會幫你自動產生，而會出現 「No documentation available.」。