1.3為WebApi創建幫助文檔

• 1.創建 API 幫助頁
• 2.將幫助頁添加到現有的項目
• 3.添加Api文檔
• 4.Under the Hood

當你創建一個網絡 API 時，它很有用來創建一個幫助頁，以便其他開發人員將知道如何調用您的 API。您可以創建的所有文檔手動，但它是自動生成盡可能多地更好。

為了簡化這一任務，ASP.NET Web API 提供一個庫自動生成幫助頁在運行時。

回到頂部

1.創建 API 幫助頁

安裝ASP.NET和Web Tools 2012.2 Update.此更新集成到 Web API 項目模板的幫助頁面。

接下來，創建一個新的 ASP.NET MVC 4 項目並選擇 Web API 項目模板。項目模板創建名為ValuesController的示例 API 控制器。該模板還創建 API 幫助頁。所有的幫助頁的代碼文件放置在項目的區域文件夾。

當您運行該應用程序時，主頁頁面包含 API 的幫助頁面的鏈接。從主頁，相對路徑是 /Help。

此鏈接為您帶來了 API 的摘要頁。

此頁的 MVC 視圖是在 Areas/HelpPage/Views/Help/Index.cshtml 中定義的。你可以編輯此頁后，可以修改布局、 介紹、 標題、 風格等等。

該頁面的主要部分是按照控制器分組的Api幫助表格。表格記錄是根據IApiExplorer接口動態生成的。（我會稍后再談談此接口）。如果您添加一個新的 API 控制器，這個表格也會自動更新。

這個Api的列會列出Http方法和相對路徑，Description列包含每個Api的描述。在下一節，我們可以看到如何從Xml文檔添加注釋。

每個Api有一個鏈接頁面，提供更加詳細的信息。包括請求體和響應體的示例。

回到頂部

2.將幫助頁添加到現有的項目

你可以在一個已經存在的項目通過Nuget包管理器去添加幫助頁面。

這個方法很有用，當你從新的一個項目而不在WebApi這個項目。

C#應用程序 ︰Install-Package Microsoft.AspNet.WebApi.HelpPage

Visual Basic應用程序 ︰Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

有兩個包，一個用於 C# 和 Visual Basic 之一。請確保使用最符合您的項目。

這個命令就會安裝必要的程序集並且為這些幫助頁創建MVC視圖（路徑為Areas/HelpPage的文件夾）。所以你需要手動添加一個鏈接跳到幫助頁面。

Url為/Help，在Razor視圖創建鏈接，請添加以下內容：

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

當然，也需要注冊區域路由規則。

在Global.asax文件，在Application_Start方法添加以下代碼，如果這不存在的話：

1 protected void Application_Start()
2 {
3     // Add this code, if not present.
4     AreaRegistration.RegisterAllAreas();5 
6     // ...
7 }

回到頂部

3.添加Api文檔

默認情況下，這個幫助頁面由documentation去替換占位的文本，你也可以使用XML文檔注釋去創建documentation。

如果你要啟用這個功能，你需要打開Areas/HelpPage/App_Start/HelpPageConfig.cs這個文件，以及注釋以下行：

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

現在啟用了XML文檔，在解決方案資源管理器，右鍵單擊該項目並選擇屬性，選擇生成頁。

在輸出下，XML文檔文件的編輯框，在編輯框中，輸入"App_Data/XmlDocument.xml"

接下來，打開ValuesController的控制器/Controllers/ValuesControler.cs，在控制器方法上添加一些注釋，例如：

 1 /// <summary>
 2 /// Gets some very important data from the server.
 3 /// </summary>
 4 public IEnumerable<string> Get()
 5 {
 6     return new string[] { "value1", "value2" };
 7 }
 8 
 9 /// <summary>
10 /// Looks up some data by ID.
11 /// </summary>
12 /// <param name="id">The ID of the data.</param>
13 public string Get(int id)
14 {
15     return "value";
16 }

提示：如果你的方法上方有三個斜杠，VS將自動插入XML的元素。

現在生成項目並且再次運行應用程序，並導航到幫助頁。這些注釋字符串應該會在Api的表格上顯示。

這個幫助頁就會從XML文件讀取字符串，當你部署應用程序的時候，請確保XML文件是存在的。

回到頂部

4.Under the Hood

這些幫助頁都是簡歷在ApiExplorer 類，它是WebApi框架的一部分。ApiExplorer 類提供了創建一個幫助頁的工具。對於每個Api來說,ApiExplorer就會包含Api一些描述。

為了這個目的，Api就是定義組合的Http方法和相對的Url路徑，例如，下面是一些不同的Api：

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

要隱藏從ApiExplorerAPI，將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的對象。