為 ASP.NET Web API 建立協助頁面（轉載）

標籤：des   http   io   os   ar   使用   sp   strong   檔案   

轉載地址：http://www.asp.net/web-api/overview/creating-web-apis/creating-api-help-pages

當建立web API 時，經常要建立一個協助頁，以便其他開發人員知道如何調用您的 API。您可以手動建立的所有文檔，但最好是儘可能多地自動產生。

為了簡化這一任務，ASP.NET Web API 提供一個庫自動產生協助頁。

建立 API 協助頁

安裝ASP.NET 和 Web 工具 2012.2 的更新。此更新整合到 Web API 項目模板的協助頁面。

接下來，建立一個新的 ASP.NET MVC 4 項目並選擇 Web API 項目模板。項目模板建立名為ValuesController的樣本 API 控制器。該模板還會建立 API 的協助頁面。所有的協助頁的代碼檔案都放在項目的地區檔案夾。

當您運行該應用程式時，首頁頁麵包含 API 的協助頁面的連結。從首頁上，相對路徑是 /Help。

此連結為您帶到 API 的摘要頁。

此頁的 MVC 視圖是在 Areas/HelpPage/Views/Help/Index.cshtml 中定義的。您可以編輯此頁後，可以修改布局、 介紹、 標題、 樣式和等等。

該頁面的主要部分是一個table布局的控制器的Api。使用IApiExplorer介面條目是動態產生的。(我會稍後再談談此介面)。如果您添加一個新的 API 控制器，在運行時自動更新的介面。

"API"列列出了 HTTP 方法和相對 URI。"說明"列中包含每個 API 的文檔。最初，該文檔是只是預留位置文字。在接下來的部分中，我將展示如何從 XML 注釋添加文檔。

每個 API 已連結到一個網頁提供更詳細資料，包括樣本請求和響應的代碼。

將協助頁面添加到現有的項目

通過使用 NuGet 封裝管理員，可以將協助頁面添加現有 Web API 項目。

從工具菜單中，選擇庫封裝管理員，然後選擇封裝管理員控制台。在封裝管理員控制台視窗中，鍵入下列命令之一：

C#應用程式：Install-Package Microsoft.AspNet.WebApi.HelpPage

此命令安裝必要的程式集並添加 MVC 視圖 （位於Area/HelpPage 檔案夾）的協助頁。您需要手動添加到協助頁的連結。URI 是 /Help。要在 razor 視圖中建立連結，請添加以下內容：

@Html.ActionLink("API", "Index", "Help", new { area = "" }, null)

此外，還要確保要註冊的Area。在 Global.asax 檔案中，添加以下代碼Application_Start的方法，如果它已不存在：

protected void Application_Start(){    // Add this code, if not present.    AreaRegistration.RegisterAllAreas();    // ...}

添加 API 文檔

預設情況下，協助頁面有檔案的預留位置字串。您可以使用XML 文件註解可以建立的文檔。若要啟用此功能，請開啟 Areas/HelpPage/App_Start/HelpPageConfig.cs 檔案和取消注釋以下行：

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

現在啟用 XML 文檔。在方案總管中，按右鍵該項目並選擇屬性。選擇產生的頁面。

根據輸出，請檢查XML 文檔檔案。在編輯框中，鍵入"App_Data/XmlDocument.xml"。

接下來，開啟ValuesController API 控制器，它在 /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/Products
• GET /api/Products/{id}
• POST /api/Products

如果一個控制器動作支援多個 HTTP 方法， ApiExplorer會將每個方法視為不同的 API。

若要隱藏從ApiExplorer的 API，將ApiExplorerSettings屬性添加到操作，將IgnoreApi設定為 true。

[ApiExplorerSettings(IgnoreApi=true)]public HttpResponseMessage Get(int id) {  }

也可以將此屬性添加到控制器，來排除整個控制器。

ApiExplorer 類從IDocumentationProvider介面擷取文檔字串。正如您看到的早些時候，協助頁面庫提供了從 XML 文檔字串中擷取檔案的IDocumentationProvider 。該代碼位於 /Areas/HelpPage/XmlDocumentationProvider.cs。通過編寫您自己的IDocumentationProvider，可以從另一個源擷取文檔。若要它捆綁起來，請在HelpPageConfigurationExtensions中定義的SetDocumentationProvider擴充方法

ApiExplorer自動調用IDocumentationProvider介面來擷取每個 API 的文檔字串。它將它們儲存在文檔屬性中的ApiDescription和ApiParameterDescription的對象。

為 ASP.NET Web API 建立協助頁面（轉載）