Asp.net Web Api开发(第四篇)Help Page配置和扩展
2016-09-30 09:40
549 查看
为了方面APP开发人员,服务端的接口都应当提供详尽的API说明。但每次有修改,既要维护代码,又要维护文档,一旦开发进度紧张,很容易导致代码与文档不一致。
Web API有一个Help Page插件,可以很方便的根据代码及注释自动生成相关API说明页面。示例DEMO下载:http://pan.baidu.com/s/1nvbG0XV
Help Page安装步骤及扩展(以VS2015为例):
右键点击WebAPI项目的引用,选择"管理NuGet程序包"
在搜索框中输入 helppage进行搜索,结果如下图:
然后在右侧边栏点击安装按钮即可进行插件安装了。
安装完成后,你会发现项目下多了不少文件:
接下来,我们对Areas/HelpPage/App_Start/HelpPageConfig.cs进行改造。
改造前,我们需要先了解下HelpPageConfig.cs,其中的Register方法是用于注册Help Page页面需要展示的API的文档的。默认情况下,该方法只支持单个文档导入,所以我们需要扩展下。
我们创建一个可多文件注册的类:
这里要注意下WebApplication2.XML,这个文件是需要我们对相关项目属性进行设置下的,让其生成相关xml文件。
然后我们来创建一个Controller用于测试。
因为创建的是Web API项目,所以这里还要修改下Global.asax,注册Area。
Web API有一个Help Page插件,可以很方便的根据代码及注释自动生成相关API说明页面。示例DEMO下载:http://pan.baidu.com/s/1nvbG0XV
Help Page安装步骤及扩展(以VS2015为例):
右键点击WebAPI项目的引用,选择"管理NuGet程序包"
在搜索框中输入 helppage进行搜索,结果如下图:
然后在右侧边栏点击安装按钮即可进行插件安装了。
安装完成后,你会发现项目下多了不少文件:
接下来,我们对Areas/HelpPage/App_Start/HelpPageConfig.cs进行改造。
改造前,我们需要先了解下HelpPageConfig.cs,其中的Register方法是用于注册Help Page页面需要展示的API的文档的。默认情况下,该方法只支持单个文档导入,所以我们需要扩展下。
我们创建一个可多文件注册的类:
using System; using System.Linq; using System.Reflection; using System.Web.Http.Controllers; using System.Web.Http.Description; using WebApplication2.Areas.HelpPage.ModelDescriptions; namespace WebApplication2.Areas.HelpPage.App_Start { public class MultiXmlDocumentationProvider : IDocumentationProvider, IModelDocumentationProvider { private readonly XmlDocumentationProvider[] Providers; public MultiXmlDocumentationProvider(params string[] paths) { this.Providers = paths.Select(p => new XmlDocumentationProvider(p)).ToArray(); } public string GetDocumentation(MemberInfo subject) { return this.GetFirstMatch(p => p.GetDocumentation(subject)); } public string GetDocumentation(Type subject) { return this.GetFirstMatch(p => p.GetDocumentation(subject)); } public string GetDocumentation(HttpControllerDescriptor subject) { return this.GetFirstMatch(p => p.GetDocumentation(subject)); } public string GetDocumentation(HttpActionDescriptor subject) { return this.GetFirstMatch(p => p.GetDocumentation(subject)); } public string GetDocumentation(HttpParameterDescriptor subject) { return this.GetFirstMatch(p => p.GetDocumentation(subject)); } public string GetResponseDocumentation(HttpActionDescriptor subject) { return this.GetFirstMatch(p => p.GetDocumentation(subject)); } private string GetFirstMatch(Func<XmlDocumentationProvider, string> expr) { return this.Providers .Select(expr) .FirstOrDefault(p => !String.IsNullOrWhiteSpace(p)); } } }然后重写HelpPageConfig.cs文件中的代码如下:
using System.Diagnostics.CodeAnalysis; using System.Web; using System.Web.Http; using WebApplication2.Areas.HelpPage.App_Start; namespace WebApplication2.Areas.HelpPage { public static class HelpPageConfig { [SuppressMessage("Microsoft.Globalization", "CA1303:Do not pass literals as localized parameters", MessageId = "WebApplication2.Areas.HelpPage.TextSample.#ctor(System.String)", Justification = "End users may choose to merge this string with existing localized resources.")] [SuppressMessage("Microsoft.Naming", "CA2204:Literals should be spelled correctly", MessageId = "bsonspec", Justification = "Part of a URI.")] public static void Register(HttpConfiguration config) { config.SetDocumentationProvider(new MultiXmlDocumentationProvider( HttpContext.Current.Server.MapPath("~/bin/WebApplication2.XML"))); } } }
这里要注意下WebApplication2.XML,这个文件是需要我们对相关项目属性进行设置下的,让其生成相关xml文件。
然后我们来创建一个Controller用于测试。
using System.Web.Http; namespace WebApplication2.Controllers { /// <summary> /// 测试响应对象 /// </summary> public struct TestResponse { /// <summary> /// 姓名 /// </summary> public string Name; /// <summary> /// 年龄 /// </summary> public int Age; } /// <summary> /// 测试 /// </summary> public class TestController : ApiController { /// <summary> /// 测试接口 /// </summary> /// <returns></returns> [HttpPost] [Route("api/300/1000")] public TestResponse JustTest() { return new TestResponse() { Name = "测试员", Age = 26 }; } } }
因为创建的是Web API项目,所以这里还要修改下Global.asax,注册Area。
using System.Web.Http; using System.Web.Mvc; namespace WebApplication2 { public class WebApiApplication : System.Web.HttpApplication { protected void Application_Start() { AreaRegistration.RegisterAllAreas(); GlobalConfiguration.Configure(WebApiConfig.Register); } } }接下来,编译运行调试起来,效果如下图。
相关文章推荐
- Asp.net Web Api开发(第四篇)Help Page配置和扩展
- 关于ASP.NET Web Api的HelpPage文档注释问题
- 关于ASP.NET Web Api的HelpPage文档注释问题
- 关于ASP.NET Web Api的HelpPage文档注释问题
- 关于ASP.NET Web Api的HelpPage文档注释问题
- 关于ASP.NET Web Api的HelpPage文档注释问题
- Creating the Help Page in ASP.NET Web API
- 创建 ASP.NET Web API的Help Page
- 关于ASP.NET Web Api的HelpPage文档注释问题
- ASP.NET中把扩展名.aspx改成自定义的扩展名.mspx,如何在IIS与.net框架中配置
- 如何在 vista 的 iis 7 上面配置 asp.net 1.1 开发环境
- asp.net开发web项目-vss集成环境配置
- 开发ASP.NET 2.0 Web应用程序时如何将App_Code文件夹中的共享代码配置生成多个Dll
- 编译ASP.NET时,提示“请确保此代码文件中定义的类与“inherits”属性匹配,并且该类扩展的基类(例如Page 或UserControl)是正确的。
- 组件开发之asp.net 2.0获取设计时页面的虚拟路径[DesignTime page's virtual path]
- ASP.NET中把扩展名.aspx改成自定义的扩展名.mspx,如何在IIS与.net框架中配置
- 手把手教你在Win2003下配置ASP.NET开发环境
- server 2008 IIS 7下asp.net开发环境部署及配置
- asp.net 开发中配置开发环境导致的问题集,winxp sp2,iis5.1,vs2005,c# 2.0
- 开发ASP.NET 2.0 Web应用程序时如何将App_Code文件夹中的共享代码配置生成多个Dll