使用多个项目生成Xml文件来显示帮助文档

Posted 2020-09-18 JustDo

终于到这了，我们首先将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，对其添加生成事件

1. copy $(SolutionDir)WebAPI2PostMan.WebModel\\App_Data\\XmlDocument.xml $(ProjectDir)\\App_Data\\WebAPI2PostMan.WebModel.XmlDocument.xml  

每次生成成功后将 WebAPI2PostMan.WebModel.XmlDocument.xml 文件拷贝到 WebAPI2PostMan项目的App_Data目录下，并更名为 WebAPI2PostMan.WebModel.XmlDocument.xml。

至此，重新生成项目，我们的描述就又回来了~

 

这篇文章若耐心看完会发现其实就改动几处而已，没必要花这么大篇幅来说明，但是对需要的人来说还是有一点帮助的。

为了方便，源代码依然在：https://github.com/yanghongjie/WebAPI2PostMan ，若你都看到这里了，顺手点下【推荐】吧(●\'◡\'●)。