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

之前使用Microsoft.AspNet.WebApi.HelpPage的时候，一直为返回对象的注释发愁，以为这是个BUG。

这个注释的解决办法其实要从其原理理解就明白了。

因为HelpPage是读取的XML文件生成的，你的对象没有生成XML文件，当然显示的是空的。

那么解决的办法如下，

1.将你的返回对象所在的库也生成XML文件，右键属性--生成。都选XML项，配置好XML文件生成路径。

2.在原有的基础上，写一个读取多个XML文件的方法。代码如下：

/// <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));

        }

    }

3.替换HelpPageConfig里面的读取方法：

//config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml")));

config.SetDocumentationProvider(new MultiXmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/XmlDocument.xml"), HttpContext.Current.Server.MapPath("~/App_Data/Api.xml")));

Api.xml为你生成的对象XML文件。

然后重新生成就OK了。

当然生成的XML文件路径要根据自己项目的路径配置好。

巴特西

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

最新文章

热门文章