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.　　

1 Type[] genericArguments = type.GetGenericArguments();
2 string genericTypeName = genericType.FullName;
3 
4 return genericTypeName;  //处理泛型不显示注释问题

View Code

 

　　

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

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

　　

　　

 1     //HelpPageConfig修改
 2     
 3     config.SetDocumentationProvider(new XmlDocumentationProvider(
 4          HttpContext.Current.Server.MapPath("~/App_Data")));
 5 
 6 
 7     //
 8 
 9     public XmlDocumentationProvider(string documentPath)
10         {
11             if (documentPath == null)
12             {
13                 throw new ArgumentNullException("documentPath");
14             }
15             var files = Directory.GetFiles(documentPath, "*.xml");
16             foreach (var file in files)
17             {
18                 XPathDocument xpath = new XPathDocument(Path.Combine(documentPath, file));
19                 _documentNavigators.Add(xpath.CreateNavigator());
20             }
21         }

View Code

 

 

 

　　3.自定义Api列表

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

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

　　

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

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

　　

 

 我们对ApiGroup页面作如下修改　　

 1 <table class="help-page-table">
 2     <thead>
 3         <tr><th>接口名称</th><th>作者</th><th>方式</th><th>接口地址</th></tr>
 4     </thead>
 5     <tbody>
 6         @foreach (var api in Model)
 7         {
 8             var apides = GetApiDesc(api.Documentation ?? "");
 9             <tr>
10                 <td class="api-documentation">
11                     <p>@apides.Desc</p>
12                 </td>
13                 <td class="api-author">
14                     <p>@apides.Author</p>
15                 </td>
16                 <td>@api.HttpMethod.Method</td>
17                 <td class="api-name"><a href="@Url.Action("Api", "Help", new { apiId = api.GetFriendlyId() })">@api.RelativePath</a></td>
18 
19             </tr>
20         }
21     </tbody>
22 </table>
23 
24 @functions{
25     public class apiDesc
26     {
27         public string Desc { get; set; }
28         public string Author { get; set; }
29     }
30 
31     public apiDesc GetApiDesc(string oriDesc)
32     {
33         apiDesc result = new apiDesc();
34 
35         var descArray = Regex.Split(oriDesc, "\r\n", RegexOptions.IgnoreCase);
36         if (descArray.Length > 1 && descArray[1] != "")
37         {
38             List<string> descList = new List<string>();
39             foreach (var item in descArray)
40             {
41                 if (item.Trim().StartsWith("author"))
42                 {
43                     result.Author = item.Trim().Remove(0, 7);
44                 }
45                 else
46                 {
47                     descList.Add(item);
48                 }
49             }
50             if (descArray.Count() > 0)
51                 result.Desc = string.Join(";", descList);
52         }
53         else
54         {
55             result.Desc = oriDesc;
56         }
57         if (string.IsNullOrEmpty(result.Desc))
58             result.Desc = "无接口描述";
59         if (string.IsNullOrEmpty(result.Author))
60             result.Author = "无作者信息";
61 
62         return result;
63     }
64 }

View Code

 

 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")；

 1 <div id="body" class="help-page">
 2     <section class="featured">
 3         <div class="content-wrapper">
 4 
 5         </div>
 6     </section>
 7     <section class="content-wrapper main-content clear-fix">
 8         @Html.DisplayForModel()
 9     </section>
10     @Html.DisplayForModel("TestClientDialogs")
11 </div>
12 @section scripts{
13 
14     @Html.DisplayForModel("TestClientReferences")
15 }

View Code

 

运行程序，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信息

 

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

 

转载于:https://www.cnblogs.com/xihao/p/10614718.html