zoukankan      html  css  js  c++  java
  • 使用多个项目生成Xml文件来显示帮助文档

    终于到这了,我们首先将Product单独作为一个项目 WebAPI2PostMan.WebModel 并引用他,查看文档如下。

    image

    你会发现,你的注释也就是属性的描述没有了。打开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.WebModelApp_DataXmlDocument.xml $(ProjectDir)App_DataWebAPI2PostMan.WebModel.XmlDocument.xml  

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

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

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

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

  • 相关阅读:
    javaweb消息中间件——rabbitmq入门
    virtual box 桥接模式(bridge adapter)下无法获取ip(determine ip failed)的解决方法
    Apache Kylin本地启动
    git操作
    Java学习总结
    Java中同步的几种实现方式
    hibernate exception nested transactions not supported 解决方法
    vue 中解决移动端使用 js sdk 在ios 上一直报invalid signature 的问题解决
    cookie 的使用
    vue 专门为了解决修改微信标题而生的项目
  • 原文地址:https://www.cnblogs.com/caoyc/p/6871791.html
Copyright © 2011-2022 走看看