做者：Mike Wassonhtml
建立Web API時，建立幫助頁面一般頗有用，以便其餘開發人員知道如何調用API。您能夠手動建立全部文檔，但最好儘量自動生成。git
爲了簡化此任務，ASP.NET Web API提供了一個用於在運行時自動生成幫助頁面的庫。github
建立API幫助頁面
安裝ASP.NET和Web Tools 2012.2更新。此更新將幫助頁面集成到Web API項目模板中。web
接下來，建立一個新的ASP.NET MVC 4項目並選擇Web API項目模板。項目模板建立一個名爲API的例子ValuesController。該模板還建立API幫助頁面。幫助頁面的全部代碼文件都放在項目的區域文件夾中。api
運行應用程序時，主頁包含指向API幫助頁面的連接。在主頁上，相對路徑爲/ Help。框架
此連接將帶您進入API摘要頁面。ide
該頁面的MVC視圖在Areas / HelpPage / Views / Help / Index.cshtml中定義。您能夠編輯此頁面來修改佈局，介紹，標題，樣式等。工具
頁面的主要部分是由控制器分組的API表格。使用IApiExplorer接口動態生成表條目。（稍後我會再談談這個界面。）若是添加了一個新的API控制器，表將在運行時自動更新。佈局
「API」列列出了HTTP方法和相對URI。「說明」列包含每一個API的文檔。最初，文檔只是佔位符文本。在下一節中，我將介紹如何從XML註釋中添加文檔。this
每一個API都有一個包含更詳細信息的頁面的連接，包括示例請求和響應實體。
將幫助頁面添加到現有項目
您可使用NuGet軟件包管理器將幫助頁面添加到現有的Web API項目。從「Web API」模板的不一樣項目模板開始，此選項頗有用。
從工具菜單中，選擇庫包管理器，而後選擇包管理器控制檯。在「 管理器管理器」窗口中，鍵入如下命令之一：
對於C＃應用程序：Install-Package Microsoft.AspNet.WebApi.HelpPage
對於Visual Basic應用程序：Install-Package Microsoft.AspNet.WebApi.HelpPage.VB
有兩個包，一個用於C＃，一個用於Visual Basic。確保使用與您的項目匹配的。
此命令安裝必要的程序集，併爲幫助頁面（位於Areas / HelpPage文件夾中）添加MVC視圖。您須要手動添加一個連接到幫助頁面。URI是/ Help。要在剃刀視圖中建立連接，請添加如下內容：
@Html.ActionLink("API", "Index", "Help", new { area = "" }, null)
另外，請務必註冊區域。在Global.asax文件中，將如下代碼添加到Application_Start方法中（若是尚未）：
protected void Application_Start() { // Add this code, if not present. AreaRegistration.RegisterAllAreas(); // ... }
添加API文檔
默認狀況下，幫助頁面具備用於文檔的佔位符字符串。您可使用XML文檔註釋來建立文檔。要啓用此功能，請打開文件區域/ HelpPage / App_Start / HelpPageConfig.cs並取消註釋如下行：
config.SetDocumentationProvider(new XmlDocumentationProvider( HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));
如今啓用XML文檔。在解決方案資源管理器中，右鍵單擊項目並選擇屬性。選擇構建頁面。
在輸出下，檢查XML文檔文件。在編輯框中，鍵入「App_Data / XmlDocument.xml」。1
接下來，打開ValuesControllerAPI控制器的代碼，該控件在/Controllers/ValuesControler.cs中定義。向控制器方法添加一些文檔註釋。例如：
/// <summary> /// Gets some very important data from the server. /// </summary> public IEnumerable<string> Get() { return new string[] { "value1", "value2" }; } /// <summary> /// Looks up some data by ID. /// </summary> /// <param name="id">The ID of the data.</param> public string Get(int id) { return "value"; }
注意
提示：若是將插入符號放置在方法上方，並鍵入三個正斜槓，Visual Studio將自動插入XML元素。而後你能夠填寫空白。
如今再次構建和運行應用程序，並導航到幫助頁面。文檔字符串應顯示在API表中。
幫助頁面在運行時從XML文件讀取字符串。（部署應用程序時，請確保部署XML文件。）
在敞篷下
幫助頁面創建在ApiExplorer類之上，該類是Web API框架的一部分。該ApiExplorer類提供的原料，用於建立一個幫助頁面。對於每一個API，ApiExplorer包含一個描述API 的ApiDescription。爲此，將「API」定義爲HTTP方法和相對URI的組合。例如，這裏有一些不一樣的API：
- GET / api /產品
- GET / api / Products / {id}
- POST / api /產品
若是控制器操做支持多種HTTP方法，則ApiExplorer將每一個方法視爲不一樣的API。
要從ApiExplorer中隱藏API ，請將ApiExplorerSettings屬性添加到操做中，並將IgnoreApi設置爲true。
[ApiExplorerSettings(IgnoreApi=true)] public HttpResponseMessage Get(int id) { }
您也能夠將此屬性添加到控制器，以排除整個控制器。
ApiExplorer類從IDocumentationProvider接口獲取文檔字符串。如前所述，幫助頁面庫提供了一個IDocumentationProvider，它從XML文檔字符串中獲取文檔。代碼位於/Areas/HelpPage/XmlDocumentationProvider.cs中。您能夠經過編寫本身的IDocumentationProvider從其餘來源獲取文檔。要鏈接它，調用SetDocumentationProvider擴展方法，在HelpPageConfigurationExtensions中定義
ApiExplorer自動調用IDocumentationProvider接口獲取每一個API的文檔字符串。它將它們存儲在ApiDescription和ApiParameterDescription對象的Documentation屬性中。