如何給你的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,修改配置文件生成位置
首先需要說明的是,這個程序包會依托于項目生成的XML配置文件來產生所有的文檔,所以你得先讓你的項目生成這個XML文件
右鍵項目選擇屬性,之后再生成一欄里面選擇輸出到XML文檔文件,那個路徑和名稱隨你怎么寫,只要一會和下面的配置對應上就OK,我這邊直接用的是默認的。
之后我們需要做的就是給這個xml的路徑寫到程序里面,配置好就可以了,打開Areas/HelpPage/App_Start/HelpPageConfig.cs 頁面,將Register函數里面的幾段注釋去掉,之后修改成剛才的路徑就ok了。
1 public static void Register(HttpConfiguration config) 2 { 3 // Uncomment the following to use the documentation from XML documentation file. 4 config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/bin/Service.xml"))); // 注:這里的路徑就是剛才說的地址,你修改成一樣的就OK了 5 6 // Uncomment the following to use "sample string" as the sample for all actions that have string as the body parameter or return type. 7 // Also, the string arrays will be used for IEnumerable<string>. The sample objects will be serialized into different media type 8 // formats by the available formatters. 9 config.SetSampleObjects(new Dictionary<Type, object> // 這段需要解放出來主要就是做sample的 10 { 11 {typeof(string), "sample string"}, 12 {typeof(IEnumerable<string>), new string[]{"sample 1", "sample 2"}} 13 });
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/5 12 /// <summary> 13 /// this is get function with a parameter named id 14 /// </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 class="help-page"> 10 <div class="content-wrapper"> 11 <div class="float-left"> 12 <h1>@ViewBag.Title</h1> 13 </div> 14 </div> 15 </header> 16 <div id="body" class="help-page"> 17 <section class="featured"> 18 <div class="content-wrapper"> 19 <h2>介紹</h2> 20 <p> 21 我修改了這里 22 </p> 23 </div> 24 </section> 25 <section class="content-wrapper main-content clear-fix"> 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,這樣我們在開發的時候就很方便了。
記在這里,以后學習!
文章列表