ASP.NET Web API 2系列(三)：查看WebAPI接口的詳細說明及測試接口

引言

前邊兩篇博客介紹了Web API的基本框架以及路由配置，這篇博客主要解決在先後端分離項目中，爲前端人員提供詳細接口說明的問題，主要是經過修改WebApi HelpPage相關代碼和添加WebApiTestClient組件實現WebAPI接口詳細說明以及接口測試。

WepAPI系列博客

ASP.NET Web API 2系列(一)：初識Web API及手動搭建基本框架

ASP.NET Web API 2系列(二)：靈活多樣的路由配置

WebApi HelpPage幫助頁

經過VS2017建立Web API應用程序（注意不是空的API應用程序），系統會自動添加HelpPage，這裏經過修改代碼和設置路徑，能夠實時查看WebAPI的接口說明。

建立Web API應用程序

新建WebAPITest解決方案，並添加WebAPITest.Web(Web API應用程序)和WebAPI.Entities(類庫)，建立過程能夠到系列博客查看，建立完成，解決方案資源管理器以下圖所示：

在Entities中添加Student類，並在Controllers中添加StudentController(Web API控制器類(V2.1))，修改相應代碼（具體參照ASP.NET Web API 2系列(二)：靈活多樣的路由配置），刪除原有的ValueController，上述操做完成後以下圖所示：

 運行程序，點擊頁面中API菜單（http://localhost:56783/Help），能夠看到API接口，以下圖所示：

 點擊上邊列表中的接口，能夠查看調用說明，以下圖所示：

 這時發現全部的說明信息都爲空（Description），接下來添加描述信息。

HelpPage顯示description

Student.cs中的相應字段和StudentController.cs中的接口添加描述信息，以下圖所示：

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 分別勾選WebAPITest.Entities和WebAPITest.Web項目【屬性-生成-輸出-XML文檔文件】，以下圖所示：

修改Areas/HelpPage/App_Start/HelpPageConfig.cs

修改 public static void Register(HttpConfiguration config)：

config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/bin")));

輸出目錄都設置到Web的bin下，具體截圖以下：

修改Areas/HelpPage/XmlDocumentationProvider.cs

添加私有變量：

private List<XPathNavigator> _documentNavigators;

修改構造函數 public XmlDocumentationProvider(string documentPath)（其中的files種的XML名字必須和生成的對應）：

 public XmlDocumentationProvider(string documentPath)
        {
            if (documentPath == null)
            {
                throw new ArgumentNullException("documentPath");
            }
            //XPathDocument xpath = new XPathDocument(documentPath);
            //_documentNavigator = xpath.CreateNavigator();
            _documentNavigators = new List<XPathNavigator>();
            var files = new[] { "WebAPITest.Web.xml", "WebAPITest.Entities.xml" };
            foreach (var file in files)
            {
                var path = Path.Combine(documentPath, file);
                if (File.Exists(path))
                {
                    XPathDocument xpath = new XPathDocument(path);
                    _documentNavigators.Add(xpath.CreateNavigator());
                }
            }
        }

添加私有方法：

  private XPathNavigator SelectSingleNode(string selectExpression)
        {
            foreach (var navigator in _documentNavigators)
            {
                var propertyNode = navigator.SelectSingleNode(selectExpression);
                if (propertyNode != null)
                    return propertyNode;
            }
            return null;
        }

用SelectSingleNode(selectExpression)替換_documentNavigator.SelectSingleNode(selectExpression)的調用，在文中大概有四處。

 此時完成添加描述的所有操做，運行程序，效果以下圖所示：

 WebApiTestClient接口測試

 WebApiTestClient介紹

WebApiTestClient組件做用主要有如下幾個：

（1）將WebApi的接口放到了瀏覽器裏面，以可視化的方式展示出來，好比咱們經過http://localhost:11095/Help這個地址就能在瀏覽器裏面看到這個服務裏面全部的API接口以及接口的詳細說明。

（2）可以詳細查看API的類說明、方法說明、參數說明、返回值說明。只須要咱們在定義方法時候加上 /// 這種詳細註釋便可，組件自動讀取註釋裏面的內容展示在界面上面。

（3）能夠修改http請求頭文件Head和請求體Body裏面的參數，指定發送http請求的特性，好比指定咱們最多見的contentType指示參數的類型。

（4）組件擁有測試接口的功能，用過Soup UI的朋友應該知道，經過Soup UI可以方便測試WebService參數以及返回值。咱們的WebApiTestClient也能夠實現相似的功能，直接經過頁面上的測試按鈕，就能測試接口。

安裝 WebApiTestClient組件

經過NuGet引入組件，以下圖所示：

 

安裝成功後，項目會自動添加一些主要文件：

Scripts\WebApiTestClient.js
Areas\HelpPage\TestClient.css
Areas\HelpPage\Views\Help\DisplayTemplates\TestClientDialogs.cshtml
Areas\HelpPage\Views\Help\DisplayTemplates\TestClientReferences.cshtml

組件使用

修改Areas/HelpPage/Views/Help/Api.cshtml，添加如下內容:

@Html.DisplayForModel("TestClientDialogs")
@section Scripts{
    <link href="~/Areas/HelpPage/HelpPage.css" rel="stylesheet" />
    @Html.DisplayForModel("TestClientReferences")
}

添加位置以下圖所示：

 添加完成後，運行程序，調用api/Student/{id}，此時發如今頁面右下角出現一個【Test API】按鈕，以下圖所示：

單擊【Test API】按鈕，能夠直接測試次API接口，具體調用後邊再講，此時發現測試頁面在當前頁面的最下端，不太美觀，以下圖所示：

研究發現，出現該問題的緣由是因爲新建的項目自帶的JQuery和Boostrap的版本太高引發，經過NuGet將JQuery修改成1.12.4，Boostrap修改成3.3.7。在此運行程序，測試頁面出現頁面中間，以下所示：

 

輸出調用參數001，點擊【Send】按鈕，測試api/Student/{id}，調用結果以下圖所示：

 其餘接口均可以經過此方法調用測試，很是的直觀、便捷。

總結

至此，完成了關於WebAPI接口查看及測試調動的所有過程，上述操做的環境VS2017和.Net Framework4.6，相關程序代碼感興趣的童鞋也能夠直接下載(頁面右上角的GitHub)。博文寫做不易但願多多支持，後續會更新更多內容，感興趣的朋友能夠加關注，歡迎留言交流！