使用多個項目生成Xml文件來顯示幫助文檔

終於到這了，咱們首先將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，對其添加生成事件

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 ，若你都看到這裏了，順手點下【推薦】吧(●'◡'●)。