关于ASP.NET Web Api的HelpPage文档注释问题

以前我用微软的HelpPage来自动生成的webAPI帮助文档。在使用了一段时间后发现只能显示Controller上面写的注释文档内容。以前总以为是微软这个类库的bug。后来才明白了是由于我的设置不当。

 

微软的HelpPage类库

 

 

controller上的注释

 

 

AlarmRecodrdDto文档

 

我们可以很清楚的看到，返回的`AlarmRecodrdDto`并没有注释文档啊！可是我已经在类库的中写过了该代码的注释的。为毛就没有呢？？？其实啊，我们的注释文档是自动生成xml文件，再由HelpPage来读取该xml中的注释信息，最后展示在页面上。那些没有注释的文档是由于我们的代码注释没有生成对应的注释xml文件，所以就没法读取啦！！！

明白问题出在哪里了就可以动手解决问题了！！！

1. 设置指定类库中要生成的注释xml路径

 

GTCASP.Services.xml

 

 

GTCASP.Models.xml

 

 

XMLDocument.xml

 

2. 添加一个可以读取xml文件信息的类

using System;using System.Linq;using System.Reflection;using System.Web.Http.Controllers;using System.Web.Http.Description;using GTCASP.Website.Areas.HelpPage.ModelDescriptions;namespace GTCASP.Website.Areas.HelpPage.Models{    /// <summary>A custom     /// <see cref="IDocumentationProvider"/>     /// that reads the API documentation from a collection of XML documentation files.    /// </summary>    public class MultiXmlDocumentationProvider : IDocumentationProvider, IModelDocumentationProvider    {        /*********    ** Properties    *********/        /// <summary>The internal documentation providers for specific files.</summary>        private readonly XmlDocumentationProvider[] Providers;        /*********        ** Public methods        *********/        /// <summary>Construct an instance.</summary>        /// <param name="paths">The physical paths to the XML documents.</param>        public MultiXmlDocumentationProvider(params string[] paths)        {            this.Providers = paths.Select(p => new XmlDocumentationProvider(p)).ToArray();        }        /// <summary>Gets the documentation for a subject.</summary>        /// <param name="subject">The subject to document.</param>        public string GetDocumentation(MemberInfo subject)        {            return this.GetFirstMatch(p => p.GetDocumentation(subject));        }        /// <summary>Gets the documentation for a subject.</summary>        /// <param name="subject">The subject to document.</param>        public string GetDocumentation(Type subject)        {            return this.GetFirstMatch(p => p.GetDocumentation(subject));        }        /// <summary>Gets the documentation for a subject.</summary>        /// <param name="subject">The subject to document.</param>        public string GetDocumentation(HttpControllerDescriptor subject)        {            return this.GetFirstMatch(p => p.GetDocumentation(subject));        }        /// <summary>Gets the documentation for a subject.</summary>        /// <param name="subject">The subject to document.</param>        public string GetDocumentation(HttpActionDescriptor subject)        {            return this.GetFirstMatch(p => p.GetDocumentation(subject));        }        /// <summary>Gets the documentation for a subject.</summary>        /// <param name="subject">The subject to document.</param>        public string GetDocumentation(HttpParameterDescriptor subject)        {            return this.GetFirstMatch(p => p.GetDocumentation(subject));        }        /// <summary>Gets the documentation for a subject.</summary>        /// <param name="subject">The subject to document.</param>        public string GetResponseDocumentation(HttpActionDescriptor subject)        {            return this.GetFirstMatch(p => p.GetDocumentation(subject));        }        /*********        ** Private methods        *********/        /// <summary>Get the first valid result from the collection of XML documentation providers.</summary>        /// <param name="expr">The method to invoke.</param>        private string GetFirstMatch(Func<XmlDocumentationProvider, string> expr)        {            return this.Providers                .Select(expr)                .FirstOrDefault(p => !String.IsNullOrWhiteSpace(p));        }    }}

请将类添加到如下位置

 

1488537641166.jpg

 

3. 修改HelpPageConfig.cs中的代码。

 

1488537734229.jpg

 

做完以上设置后，大功告成。妹子，现在我们可以出去玩啦！！！

咦，妹子人呢？