作者:Mike Wasson
創建Web API時,創建幫助頁面通常很有用,以便其他開發人員知道如何調用API。您可以手動創建所有文檔,但最好盡可能自動生成。
為了簡化此任務,ASP.NET Web API提供了一個用于在運行時自動生成幫助頁面的庫。
創建API幫助頁面
安裝ASP.NET和Web Tools 2012.2更新。此更新將幫助頁面集成到Web API項目模板中。
接下來,創建一個新的ASP.NET MVC 4項目并選擇Web API項目模板。項目模板創建一個名為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”模板的不同項目模板開始,此選項很有用。
從工具菜單中,選擇庫包管理器,然后選擇包管理器控制臺。在“ 管理器管理器”窗口中,鍵入以下命令之一:
對于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()
{
添加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
接下來,打開ValuesController
API控制器的代碼,該控件在/Controllers/ValuesControler.cs中定義。向控制器方法添加一些文檔注釋。例如:
注意
提示:如果將插入符號放置在方法上方,并鍵入三個正斜杠,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屬性中。
留言列表