ASP.NET Web API 2：建立API協助頁面

標籤：

     當你建立了一個web API服務之後，再建一個API協助頁面是很有好處的，這樣其他開發人員就會很清楚地知道如何調用你的API介面。你可以選擇自己手工建立，但是如果能自動產生豈不是更好。為了簡化這項任務， ASP.NET Web API提供了一個在運行時自動產生協助頁的庫。    在項目中添加協助頁，首先使用NuGet安裝Microsoft.AspNet.WebApi.HelpPage庫  

安裝成功後，啟動項目有可能會報的異常  引起異常的原因是Microsoft.AspNet.WebApi.HelpPage庫要依賴於如下程式集，如果項目中使用的程式集版本低於它依賴的版本，NuGet就會把這些程式集升級到依賴的版本。升級之後引起了本地程式集和GAC的程式集衝突。解決該問題的辦法是，在項目的Web.config設定檔中的runtime節點，添加：

< dependentAssembly>        < assemblyIdentity name = "System.Web.WebPages.Razor " publicKeyToken =" 31bf3856ad364e35 "/>        < bindingRedirect oldVersion = "1.0.0.0-3.0.0.0 " newVersion =" 3.0.0.0 "/>      </ dependentAssembly >

在項目Areas 檔案夾下就自動產生了有關協助頁的所有代碼檔案

啟動項目，協助頁的相對路徑是/Help，如果你新增加了API控制器，協助頁內容會在運行時自動更新。協助頁對應的MVC視圖在項目中的路徑是Areas/HelpPage/Views/Help/Index.cshtml，你可以隨自己的意願定製該視圖的布局、介紹、標題、樣式等等。預設產生的協助頁有很多沒什麼實際意義的佔位字串。你可以使用XML文檔注釋功能來建立有意義的文檔。要開啟該功能，需要開啟Areas/HelpPage/App_Start/HelpPageConfig.cs檔案，取消下面這句代碼的注釋：

// Uncomment the following to use the documentation from XML documentation file.config.SetDocumentationProvider( new XmlDocumentationProvider ( HttpContext.Current.Server.MapPath( "~/App_Data/XmlDocument.xml" )));

然後在方案總管，右鍵項目名稱，選擇屬性，選擇產生，在輸出配置項，勾選XML文檔檔案，修改輸出路徑為App_Data/XmlDocument.xml然後開啟API控制器檔案，通過XML文檔注釋方式(///方式)給控制器的Action方法添加註釋

/// <summary>/// 查詢指定ID的商品資訊/// </summary>/// <param name="id"> 商品ID </param>/// <returns> 查詢到的商品記錄 </returns>[ HttpGet]public Product Get( int id){    return repository.Products.FirstOrDefault(p => p.ProductId == id);}

重新編譯運行項目，導航到協助頁，添加的注釋資訊就顯示到了協助頁如果要協助頁上隱藏某個API介面的資訊，可以給該Action添加ApiExplorerSettings特性同時 IgnoreApi屬性設定為true

/// <summary>/// 擷取商品列表/// </summary>/// <returns> 商品列表 </returns>[ ApiExplorerSettings(IgnoreApi = true )]public IEnumerable < Product> Get(){    return repository.Products;}

你也可以給控制器添加該特性，整個控制器的資訊都不會出現在協助頁上。  

ASP.NET Web API 2：建立API協助頁面