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中是以 隔开的一个字符串，这样我们就可以通过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, "
", RegexOptions.IgnoreCase);
        if (descArray.Length > 1 && descArray[1] != "")
        {
            List<string> descList = new List<string>();
            foreach (var item in descArray)
            {
                if (item.Trim().StartsWith("author"))
                {
                    result.Author = item.Trim().Remove(0, 7);
                }
                else
                {
                    descList.Add(item);
                }
            }
            if (descArray.Count() > 0)
                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 {
    30%;
}

.api-author {
    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信息

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