你的位置:首页 > ASP.net教程

[ASP.net教程]如何在Web项目中给没有添加API核心组件添加APIController的帮助页HelpPage

前言:

  ASP.NET中的Web项目可以通过APIController控制器来为其他项目提供接口。  而我们在调试这些接口时,可以选择单元测试,网页测试(Get接口),自己写测试代码或者第三方测试工具等等(如:PostMan可以发送GET/POST请求)。 

  但这里为大家介绍一种新的调试工具:微软提供的一种关于APIController控制器说明帮助页+测试(借助第三方)的方法来帮助开发。  废话不多说,请看原文:

 

  以下文章转载自:http://www.cnblogs.com/pmars/p/3673654.html

 

  如何给你的ASP.NET页面添加HelpPage

  最近写了一些webAPI,所以需要搞一套API的帮助文档,google了一下,发现这是可以自动生成的,以下就是如何自动生成HelpPage的说明。

  参考:http://www.asp.net/web-api/overview/creating-web-apis/creating-api-help-pages

  其实我也是按照上面的说法一步步走的,只是上面是英文,我进行一个简单的翻译,并且,在其中有些地方做了更改,也在这边记录一下!

1,新建一个项目:

   

  确认新建项目,右键项目属性,确保我们当前的项目是Framework4.5的(4.0及其以下的下面的安装包是安装不成功的,记住,这是血的教训)

  

2,添加引用包

  右键引用,选择管理NuGet程序包(你得先配置好这个,具体如何配置百度一下就OK了)

  

  之后搜索helppage即可,找到的第一个既是我们需要添加的asp.net的helppage程序包

  

  点击安装即可,这安装的速度得取决于你的网速,反正我这边特慢,有的时候还得安装好多次才可以。

  

  现在Help page就已经生成了,右键项目-》调试-》启动新实例,之后再页面URL后面写上 /Help 看看(注:我们的端口应该不会一样,无妨)

  

  这时候你会发现,页面什么都没有,不急,往下走。

3,修改配置文件生成位置

  首先需要说明的是,这个程序包会依托于项目生成的

  右键项目选择属性,之后再生成一栏里面选择输出到

  

  之后我们需要做的就是给这个复制代码

 1      public static void Register(HttpConfiguration config) 2     { 3       // Uncomment the following to use the documentation from 复制代码

    

4,添加Controller

  OK,现在基本条件已经备齐,只剩下需要显示的东西了,我们创建一个controller,之后添加一个接口

  

  添加Controller之后,里面会有一些自动生成的API,现在你可以去刷新一下那个Help页面,看看是否有货了...

  

  是不是发现,API已经显示出来了,但是并没有有用的描述在页面上,我们加上就可以了

  我只修改了两个函数来看看效果:

复制代码
 1      // GET api/crab 2     /// <summary> 3     /// this is get function without parameter 4     /// </summary> 5     /// <returns>function return value</returns> 6     public IEnumerable<string> Get() 7     { 8       return new string[] { "value1", "value2" }; 9     }10 11     // GET api/crab/512     /// <summary>13     /// this is get function with a parameter named id14     /// </summary>15     /// <param name="id"></param>16     /// <returns>function return value</returns>17     public string Get(int id)18     {19       return "value";20     }
复制代码

 

    

  OK,现在的页面已经变了,你可以根据你的需求来编写Help page了。

5,其他风格的API

  可以发现,默认生成的都是一些RestAPI,我对这个一点都不感冒,所以,我打算换一种写法:

复制代码
 1    public class CrabController : ApiController 2   { 3     /// <summary> 4     /// 测试方法 5     /// </summary> 6     /// <param name="msg1">串1</param> 7     /// <param name="msg2">串2</param> 8     /// <returns>两个字符串的连接串</returns> 9     [System.Web.Http.AcceptVerbs("GET")]10     [System.Web.Http.ActionName("TestMethod")]11     public string TestMethod(string msg1,string msg2)12     {13       return msg1 + msg2;14     }15   }
复制代码

 

  这个时候,我们还需要修改一下配置文件,否则你会发现,他的API名称变成了controller的名字

  

  找到路径 App_Start/WebApiConfig.cs,修改Register函数如下:

复制代码
1      public static void Register(HttpConfiguration config)2     {3       config.Routes.MapHttpRoute(4         name: "DefaultApi",5         routeTemplate: "{controller}/{action}",    // 此处进行了修改6         defaults: new { id = RouteParameter.Optional }7       );8     }
复制代码

 

  现在我们刷新一下页面:

  

  OK,这才是我想要的。

6,修改标题显示的内容

  为了个性化,我需要修改一下标题和介绍部分的内容,找到文件:Area/Views/Help/Index.cshtml,修改部分代码为:

复制代码
 1 @{ 2   ViewBag.Title = "这里是需要修改的Title"; 3 4   // Group APIs by controller 5   ILookup<HttpControllerDescriptor, ApiDescription> apiGroups = Model.ToLookup(api => api.ActionDescriptor.ControllerDescriptor); 6 } 7 8 <link type="text/css" href="~/Areas/HelpPage/HelpPage.css" rel="stylesheet" /> 9 <header >10   <div >11     <div >12       <h1>@ViewBag.Title</h1>13     </div>14   </div>15 </header>16 <div id="body" >17   <section >18     <div >19       <h2>介绍</h2>20       <p>21         我修改了这里22       </p>23     </div>24   </section>25   <section >26     @foreach (var group in apiGroups)27     {28       @Html.DisplayFor(m => group, "ApiGroup")29     }30   </section>31 </div>
复制代码

 现在的页面:

  

7,这里面的坑

  我在用的时候发现里面有个坑,找到文件:Areas/HelpPage/ModelDescriptions/ModelNameHelper.cs

  里面有一段代码:genericTypeName = genericTypeName.Substring(0, genericTypeName.IndexOf('`'));

  这段代码,如果当genericTypeName字符串中没有'`'的时候,是会出问题的,所以我修改了一下这段代码:

1           var index = genericTypeName.IndexOf('`');2         genericTypeName = genericTypeName.Substring(0, index != -1 ? index : genericTypeName.Length);

 8,不在页面显示API

  其实很多的函数是不需要对外公布的,那我们可以通过以下代码来设置:

1 [ApiExplorerSettings(IgnoreApi=true)]2 public HttpResponseMessage Get(int id) { }

 

  OK,这个问题基本上就是这些,现在HelpPage已经可以使用了,下一篇文章我打算写写Test Client,就是说,在help page内放入一个测试工具,连接在此:http://www.cnblogs.com/pmars/p/3673811.html,这样我们在开发的时候就很方便了。