在這篇文章中

創(chuàng)建API幫助頁面

將幫助頁面添加到現(xiàn)有項目

添加API文檔

在敞篷下

下一步

作者：Mike Wasson

創(chuàng)建Web API時，創(chuàng)建幫助頁面通常很有用，以便其他開發(fā)人員知道如何調(diào)用API。您可以手動創(chuàng)建所有文檔，但最好盡可能自動生成。

為了簡化此任務(wù)，ASP.NET Web API提供了一個用于在運行時自動生成幫助頁面的庫。

創(chuàng)建API幫助頁面

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

接下來，創(chuàng)建一個新的ASP.NET MVC 4項目并選擇Web API項目模板。項目模板創(chuàng)建一個名為API的例子ValuesController。該模板還創(chuàng)建API幫助頁面。幫助頁面的所有代碼文件都放在項目的區(qū)域文件夾中。

運行應(yīng)用程序時，主頁包含指向API幫助頁面的鏈接。在主頁上，相對路徑為/ Help。

此鏈接將帶您進(jìn)入API摘要頁面。

該頁面的MVC視圖在Areas / HelpPage / Views / Help / Index.cshtml中定義。您可以編輯此頁面來修改布局，介紹，標(biāo)題，樣式等。

頁面的主要部分是由控制器分組的API表格。使用IApiExplorer接口動態(tài)生成表條目。（稍后我會再談?wù)勥@個界面。）如果添加了一個新的API控制器，表將在運行時自動更新。

“API”列列出了HTTP方法和相對URI?！罢f明”列包含每個API的文檔。最初，文檔只是占位符文本。在下一節(jié)中，我將介紹如何從XML注釋中添加文檔。

每個API都有一個包含更詳細(xì)信息的頁面的鏈接，包括示例請求和響應(yīng)實體。

將幫助頁面添加到現(xiàn)有項目

您可以使用NuGet軟件包管理器將幫助頁面添加到現(xiàn)有的Web API項目。從“Web API”模板的不同項目模板開始，此選項很有用。

從工具菜單中，選擇庫包管理器，然后選擇包管理器控制臺。在“?管理器管理器”窗口中，鍵入以下命令之一：

對于C＃應(yīng)用程序：Install-Package Microsoft.AspNet.WebApi.HelpPage

對于Visual Basic應(yīng)用程序：Install-Package Microsoft.AspNet.WebApi.HelpPage.VB

有兩個包，一個用于C＃，一個用于Visual Basic。確保使用與您的項目匹配的。

此命令安裝必要的程序集，并為幫助頁面（位于Areas / HelpPage文件夾中）添加MVC視圖。您需要手動添加一個鏈接到幫助頁面。URI是/ Help。要在剃刀視圖中創(chuàng)建鏈接，請?zhí)砑右韵聝?nèi)容：

CSHTML復(fù)制 @Html.ActionLink("API", "Index", "Help", new { area = "" }, null)

另外，請務(wù)必注冊區(qū)域。在Global.asax文件中，將以下代碼添加到Application_Start方法中（如果還沒有）：

C＃復(fù)制 protected void Application_Start() { // Add this code, if not present. AreaRegistration.RegisterAllAreas(); // ... }

添加API文檔

默認(rèn)情況下，幫助頁面具有用于文檔的占位符字符串。您可以使用XML文檔注釋來創(chuàng)建文檔。要啟用此功能，請打開文件區(qū)域/ HelpPage / App_Start / HelpPageConfig.cs并取消注釋以下行：

C＃復(fù)制 config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

現(xiàn)在啟用XML文檔。在解決方案資源管理器中，右鍵單擊項目并選擇屬性。選擇構(gòu)建頁面。

在輸出下，檢查XML文檔文件。在編輯框中，鍵入“App_Data / XmlDocument.xml”。1

接下來，打開ValuesControllerAPI控制器的代碼，該控件在/Controllers/ValuesControler.cs中定義。向控制器方法添加一些文檔注釋。例如：

C＃復(fù)制 /// <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元素。然后你可以填寫空白。

現(xiàn)在再次構(gòu)建和運行應(yīng)用程序，并導(dǎo)航到幫助頁面。文檔字符串應(yīng)顯示在API表中。

幫助頁面在運行時從XML文件讀取字符串。（部署應(yīng)用程序時，請確保部署XML文件。）

在敞篷下

幫助頁面建立在ApiExplorer類之上，該類是Web API框架的一部分。該ApiExplorer類提供的原料，用于創(chuàng)建一個幫助頁面。對于每個API，ApiExplorer包含一個描述API?的ApiDescription。為此，將“API”定義為HTTP方法和相對URI的組合。例如，這里有一些不同的API：

• GET / api /產(chǎn)品
• GET / api / Products / {id}
• POST / api /產(chǎn)品

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

要從ApiExplorer中隱藏API?，請將ApiExplorerSettings屬性添加到操作中，并將IgnoreApi設(shè)置為true。

C＃復(fù)制 [ApiExplorerSettings(IgnoreApi=true)] public HttpResponseMessage Get(int id) { }

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

ApiExplorer類從IDocumentationProvider接口獲取文檔字符串。如前所述，幫助頁面庫提供了一個IDocumentationProvider，它從XML文檔字符串中獲取文檔。代碼位于/Areas/HelpPage/XmlDocumentationProvider.cs中。您可以通過編寫自己的IDocumentationProvider從其他來源獲取文檔。要連接它，調(diào)用SetDocumentationProvider擴展方法，在HelpPageConfigurationExtensions中定義

ApiExplorer自動調(diào)用IDocumentationProvider接口獲取每個API的文檔字符串。它將它們存儲在ApiDescription和ApiParameterDescription對象的Documentation屬性中。

轉(zhuǎn)載于:https://www.cnblogs.com/X-Jonney/p/7680063.html

總結(jié)

以上是生活随笔為你收集整理的Web API 2 入门——创建ASP.NET Web API的帮助页面（谷歌翻译）的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。