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
接下來,打開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 /產品
- 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的幫助頁面(谷歌翻譯)