Web API 2 入門——創建ASP.NET Web API的幫助頁面（谷歌翻譯）
在這篇文章中
- 創建API幫助頁面
- 將幫助頁面添加到現有項目
- 添加API文檔
- 在敞篷下
- 下一步
作者：Mike Wasson
創建Web API時，創建幫助頁面通常很有用，以便其他開發人員知道如何調用API。您可以手動創建所有文檔，但最好盡可能自動生成。
為了簡化此任務，ASP.NET Web API提供了一個用於在運行時自動生成幫助頁面的庫。
創建API幫助頁面
安裝ASP.NET和Web Tools 2012.2更新。此更新將幫助頁面集成到Web API項目模板中。
接下來，創建一個新的ASP.NET MVC 4項目並選擇Web API項目模板。ValuesController。該模板還創建API幫助頁面。幫助頁面的所有代碼文件都放在項目的區域文件夾中。
運行應用程序時，主頁包含指向API幫助頁面的鏈接。在主頁上，相對路徑為/ Help。
此鏈接將帶您進入API摘要頁面。
該頁面的MVC視圖在Areas / HelpPage / Views / Help / Index.cshtml中定義。您可以編輯此頁面來修改布局，介紹，標題，樣式等。
頁面的主要部分是由控制器分組的API表格。使用IApiExplorer接口動態生成表條目。（稍後我會再談談這個界面。）如果添加了一個新的API控制器，表將在運行時自動更新。
“API”列列出了HTTP方法和相對URI。“說明”列包含每個API的文檔。最初，文檔只是占位符文本。在下一節中，我將介紹如何從XML註釋中添加文檔。
每個API都有一個包含更詳細信息的頁面的鏈接，包括示例請求和響應實體。
將幫助頁面添加到現有項目
您可以使用NuGet軟件包管理器將幫助頁面添加到現有的Web API項目。從“Web API”模板的不同項目模板開始，此選項很有用。
從工具菜單中，選擇庫包管理器，然後選擇包管理器控制臺。在“ 管理器管理器”窗口中，鍵入以下命令之一：
對於
Install-Package Microsoft.AspNet.WebApi.HelpPage
對於Visual Basic應用程序：Install-Package Microsoft.AspNet.WebApi.HelpPage.VB
有兩個包，一個用於C＃，一個用於Visual Basic。確保使用與您的項目匹配的。
此命令安裝必要的程序集，並為幫助頁面（位於Areas / HelpPage文件夾中）添加MVC視圖。您需要手動添加一個鏈接到幫助頁面。URI是/ Help。要在剃刀視圖中創建鏈接，請添加以下內容：
CSHTML@Html.ActionLink("API", "Index", "Help", new { area = "" }, null)
另外，請務必註冊區域。在Global.asax文件中，將以下代碼添加到Application_Start方法中（如果還沒有）：
C＃protected void Application_Start()
{
// Add this code, if not present.
AreaRegistration.RegisterAllAreas();
// ...
}
添加API文檔
默認情況下，幫助頁面具有用於文檔的占位符字符串。您可以使用XML文檔註釋來創建文檔。要啟用此功能，請打開文件區域/ HelpPage / App_Start / HelpPageConfig.cs並取消註釋以下行：
C＃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。
C＃[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屬性中。
Web API 2 入門——創建ASP.NET Web API的幫助頁面（谷歌翻譯）