Web API使用记录系列（二）HelpPage优化与WebApiTestClient

　　继续使用记录的第二节，HelpPage的优化与测试工具WebApiTestClient的使用。

　　之前没怎么整理博客，都是记录一下笔记，真正好好整理发现没想像的那么简单。不管怎么说还是培养下写博客的习惯吧，不管写的好与不好，学习了总要分享一下才对，开干！

　　本节目录

　　HelpPage页面修改+自定义api列表

　　　页面修改

　　　显示备注与Model的描述信息

　　　自定义api列表

　　测试工具WebApiTestClient的使用

　　　安装与配置

　　　固定header参数处理

　　正文开始！

　　一、HelpPage页面修改+自定义api列表

　　如果使用的较低版本的api，没有HelpPage的话可以使用nuget安装HelpPage　　

install-package Microsoft.AspNet.WebApi.HelpPage

　　

　　1.页面基本的文字样式等修改

　　   我这里为了截图方便之更改了文字信息，个人可根据自己的需要修改

　　

　　黑色背景部分的文件在根目录Views/Shared/_Layout.cshtml，不是helppage下的模板页

　　中间内容区域是HelpPage下的Index.cshtml页面

　　2.显示备注与Model的描述信息

　　第一步：生成XML文件，右键项目--属性--生成选项卡（左侧）--输出模块（右侧），勾选XML文档文件，并配置路径和文件名

　　

　　第二步：修改HelpPage的配置信息（HelpPage/App_Start/HelpPageConfig.cs），将Register中的下面这句话取消注释，并将MapPath中的文件地址改成第一步中配置的

　　

config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/SampleAPI.xml")));

　　启动项目，再看一下Help页面Api列表中是不是已经显示出了你的备注内容，嘿嘿~

　　

　　扩展：

　　①泛型Model的属性备注内容不显示

　　方案：修改XmlDocumentationProvider.cs中的方法GetTypeName，在string genericTypeName = genericType.FullName;后直接return.　　

 Type[] genericArguments = type.GetGenericArguments();
 string genericTypeName = genericType.FullName;

 return genericTypeName;  //处理泛型不显示注释问题

　　

　　②接口返回Model或入参Model不在当前API项目中

　　方案：将Model所在项目的Xml生成路径配置到API项目的App_Data下，然后修改HelpPageConfig和XmlDocumentationProvider两个文件

　　

　　

     //HelpPageConfig修改

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

     //

     public XmlDocumentationProvider(string documentPath)
         {
             if (documentPath == null)
             {
                 throw new ArgumentNullException("documentPath");
             }
             var files = Directory.GetFiles(documentPath, "*.xml");
             foreach (var file in files)
             {
                 XPathDocument xpath = new XPathDocument(Path.Combine(documentPath, file));
                 _documentNavigators.Add(xpath.CreateNavigator());
             }
         }

　　3.自定义Api列表

　　   这是我们第一部分主要想说的，HelpPage自带的API列表只有简单的api地址、描述等信息，非常简单，这里我们要做的是增加我们自己想要的一些个性化内容。　　

　　示例以增加api创建作者为目标，作者可以让查询帮助文档的人知道这个接口是谁写的，方便联系相关负责人

　　

　　文件：列表部分代码位于HelpPage/Views/Help/DisplayTemplates/ApiGroup.cshtml

　　主旨思路：通过api接口的Description来实现我们的效果，通过断点跟踪，发现多行的注释在Documentation中是以\r\n隔开的一个字符串，这样我们就可以通过Documentation来做文章

　　

我们对ApiGroup页面作如下修改　　

 <table class="help-page-table">
     <thead>
         <tr><th>接口名称</th><th>作者</th><th>方式</th><th>接口地址</th></tr>
     </thead>
     <tbody>
         @foreach (var api in Model)
         {
             var apides = GetApiDesc(api.Documentation ?? "");
             <tr>
                 <td class="api-documentation">
                     <p>@apides.Desc</p>
                 </td>
                 <td class="api-author">
                     <p>@apides.Author</p>
                 </td>
                 <td>@api.HttpMethod.Method</td>
                 <td class="api-name"><a href="@Url.Action("Api", "Help", new { apiId = api.GetFriendlyId() })">@api.RelativePath</a></td>

             </tr>
         }
     </tbody>
 </table>

 @functions{
     public class apiDesc
     {
         public string Desc { get; set; }
         public string Author { get; set; }
     }

     public apiDesc GetApiDesc(string oriDesc)
     {
         apiDesc result = new apiDesc();

         var descArray = Regex.Split(oriDesc, "\r\n", RegexOptions.IgnoreCase);
         if (descArray.Length >  && descArray[] != "")
         {
             List<string> descList = new List<string>();
             foreach (var item in descArray)
             {
                 if (item.Trim().StartsWith("author"))
                 {
                     result.Author = item.Trim().Remove(, );
                 }
                 else
                 {
                     descList.Add(item);
                 }
             }
             if (descArray.Count() > )
                 result.Desc = string.Join(";", descList);
         }
         else
         {
             result.Desc = oriDesc;
         }
         if (string.IsNullOrEmpty(result.Desc))
             result.Desc = "无接口描述";
         if (string.IsNullOrEmpty(result.Author))
             result.Author = "无作者信息";

         return result;
     }
 }

HelpPage.css修改如下：

.help-page .api-documentation {
    width: 30%;
}

.api-author {
    width: 30%;
}

注释中作者信息遵循 author:作者名（如曦昊）这个约定规则（规则可根据自己喜欢改）

启动刷新Help页面，会看到api列表页面布局改变并且最重要的是显示出了我么备注的作者信息。

这里讲解的是作者信息的添加方法，其它的可以自行发挥想象力去增加自己需要的功能效果。

二、测试工具WebApiTestClient的使用

1.安装与配置

apitest开源地址：https://github.com/yaohuang/WebApiTestClient

WebApiTestlient是一个非常好用又使用简单的 ASP.NET Web API接口测试工具

第一步：使用nuget安装（ Install-Package WebApiTestClient -Version 1.1.1 ）

第二步：在Api.cshtml页面添加代码  @Html.DisplayForModel("TestClientDialogs")；@Html.DisplayForModel("TestClientReferences")；

 <div id="body" class="help-page">
     <section class="featured">
         <div class="content-wrapper">

         </div>
     </section>
     <section class="content-wrapper main-content clear-fix">
         @Html.DisplayForModel()
     </section>
     @Html.DisplayForModel("TestClientDialogs")
 </div>
 @section scripts{

     @Html.DisplayForModel("TestClientReferences")
 }

运行程序，Help页面随便点一个接口地址进去，你会发现页面右下角有一个TestClient的按钮，点击在打开的窗口中点击“send”即可进行接口的请求操作

2.固定header参数处理

如果我们在测试接口的时候，需要为接口传固定的header信息，那我们需要在testclient弹窗中“Add Header”，然后填写header键值信息。

但如果每个接口都需要填写相同的固定header信息，我们每次都去添加是不是很麻烦？这个时候我们就会想，直接在代码中写死不就ok了，很简单啊~

是的，没错，就是这么简单，但需要注意的是，testclient使用的是knockout.js，所以不能在cshtml页面上修改，我们需要在/scripts/WebApiTestClient.js中进行修改。

文件：WebApiTestClient.js

位置：TestClientViewModel 方法中的// Initiate the Knockout bindings处

代码：addOrReplaceHeader(self.RequestHeaders, "key", "value");

修改完成，即可在每一个接口的测试时都自动加上配置的header信息

本节记录到这里，有不对的地方希望大家帮忙指正修改，感谢！