标签:methods model 方式 files sub match tor img images
终于到这了,我们首先将Product单独作为一个项目 WebAPI2PostMan.WebModel 并引用他,查看文档如下。
你会发现,你的注释也就是属性的描述没有了。打开App_Data/XmlDocument.xml文件对比之前P没移动roduct的xml文件确实Product类的描述确实没有了,因为此处的XmlDocument.xml文件是项目的生成描述文件,不在此项目
内定义的文件是不会生成在这个文件内的,那真实的需求是我们确确实实需要将所有Request和Response单独定义在一个项目内供其它项目引用,可能是单元测试也可能是我们封装的WebAPI客户端(此处下篇文章介绍)。
带着这个疑问找到了这样一篇文章 http://stackoverflow.com/questions/21895257/how-can-xml-documentation-for-web-api-include-documentation-from-beyond-the-main
该文章提供了3种办法,这里只介绍我认为合理的方法,那那就是我们就需要将 WebAPI2PostMan.WebModel 的生成属性也勾选XML文档文件,就是也生成一个xml文档,同时拓展出一个新的Xml文档加载方式
在目录 ~/Areas/HelpPage/ 下新增一个名为 MultiXmlDocumentationProvider.cs 的类。
1 public class MultiXmlDocumentationProvider : IDocumentationProvider, IModelDocumentationProvider 2 { 3 /********* 4 ** Properties 5 *********/ 6 /// <summary>The internal documentation providers for specific files.</summary> 7 private readonly XmlDocumentationProvider[] Providers; 8 9 10 /********* 11 ** Public methods 12 *********/ 13 /// <summary>Construct an instance.</summary> 14 /// <param name="paths">The physical paths to the XML documents.</param> 15 public MultiXmlDocumentationProvider(params string[] paths) 16 { 17 this.Providers = paths.Select(p => new XmlDocumentationProvider(p)).ToArray(); 18 } 19 20 /// <summary>Gets the documentation for a subject.</summary> 21 /// <param name="subject">The subject to document.</param> 22 public string GetDocumentation(MemberInfo subject) 23 { 24 return this.GetFirstMatch(p => p.GetDocumentation(subject)); 25 } 26 27 /// <summary>Gets the documentation for a subject.</summary> 28 /// <param name="subject">The subject to document.</param> 29 public string GetDocumentation(Type subject) 30 { 31 return this.GetFirstMatch(p => p.GetDocumentation(subject)); 32 } 33 34 /// <summary>Gets the documentation for a subject.</summary> 35 /// <param name="subject">The subject to document.</param> 36 public string GetDocumentation(HttpControllerDescriptor subject) 37 { 38 return this.GetFirstMatch(p => p.GetDocumentation(subject)); 39 } 40 41 /// <summary>Gets the documentation for a subject.</summary> 42 /// <param name="subject">The subject to document.</param> 43 public string GetDocumentation(HttpActionDescriptor subject) 44 { 45 return this.GetFirstMatch(p => p.GetDocumentation(subject)); 46 } 47 48 /// <summary>Gets the documentation for a subject.</summary> 49 /// <param name="subject">The subject to document.</param> 50 public string GetDocumentation(HttpParameterDescriptor subject) 51 { 52 return this.GetFirstMatch(p => p.GetDocumentation(subject)); 53 } 54 55 /// <summary>Gets the documentation for a subject.</summary> 56 /// <param name="subject">The subject to document.</param> 57 public string GetResponseDocumentation(HttpActionDescriptor subject) 58 { 59 return this.GetFirstMatch(p => p.GetDocumentation(subject)); 60 } 61 62 63 /********* 64 ** Private methods 65 *********/ 66 /// <summary>Get the first valid result from the collection of XML documentation providers.</summary> 67 /// <param name="expr">The method to invoke.</param> 68 private string GetFirstMatch(Func<XmlDocumentationProvider, string> expr) 69 { 70 return this.Providers 71 .Select(expr) 72 .FirstOrDefault(p => !String.IsNullOrWhiteSpace(p)); 73 } 74 }
接着替换掉原始 ~/Areas/HelpPage/HelpPageConfig.cs 内的配置。
1 //config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml"))); 2 config.SetDocumentationProvider(new MultiXmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml"), HttpContext.Current.Server.MapPath("~/App_Data/Api.xml")));
那这里你可以选择多个文档xml放置于不同位置也可以采用将其都放置于WebAPI项目下的App_Data下。
为了方便我们在WebAPI项目下,这里指 WebAPI2PostMan,对其添加生成事件
每次生成成功后将 WebAPI2PostMan.WebModel.XmlDocument.xml 文件拷贝到 WebAPI2PostMan项目的App_Data目录下,并更名为 WebAPI2PostMan.WebModel.XmlDocument.xml。
至此,重新生成项目,我们的描述就又回来了~
这篇文章若耐心看完会发现其实就改动几处而已,没必要花这么大篇幅来说明,但是对需要的人来说还是有一点帮助的。
为了方便,源代码依然在:https://github.com/yanghongjie/WebAPI2PostMan ,若你都看到这里了,顺手点下【推荐】吧(●‘?‘●)。
标签:methods model 方式 files sub match tor img images
原文地址:http://www.cnblogs.com/caoyc/p/6871791.html