关于ASP.NET Web Api的HelpPage文档注释问题
以前我用微软的HelpPage来自动生成的webAPI帮助文档。在使用了一段时间后发现只能显示Controller上面写的注释文档内容。以前总以为是微软这个类库的bug。后来才明白了是由于我的设置不当。
![微软的HelpPage类库 enter description here](http://ww1.sinaimg.cn/large/6d132e10jw1fd9t8cla7qj20r2021q3z.jpg)
微软的HelpPage类库
![controller上的注释 enter description here](http://ww1.sinaimg.cn/large/6d132e10jw1fd9trsvh62j21760g9jte.jpg)
controller上的注释
![AlarmRecodrdDto文档 enter description here](http://ww4.sinaimg.cn/large/6d132e10jw1fd9tst97ijj21810hmdig.jpg)
AlarmRecodrdDto文档
我们可以很清楚的看到,返回的`AlarmRecodrdDto`并没有注释文档啊!可是我已经在类库的中写过了该代码的注释的。为毛就没有呢???
其实啊,我们的注释文档是自动生成xml文件,再由HelpPage来读取该xml中的注释信息,最后展示在页面上。那些没有注释的文档是由于我们的代码注释没有生成对应的注释xml文件,所以就没法读取啦!!!
明白问题出在哪里了就可以动手解决问题了!!!
1. 设置指定类库中要生成的注释xml路径
![GTCASP.Services.xml enter description here](http://ww2.sinaimg.cn/large/6d132e10jw1fd9u0yksosj20mk0jxade.jpg)
GTCASP.Services.xml
![GTCASP.Models.xml enter description here](http://ww1.sinaimg.cn/large/6d132e10jw1fd9u1yftyej20o80jh77n.jpg)
GTCASP.Models.xml
![XMLDocument.xml enter description here](http://ww1.sinaimg.cn/large/6d132e10jw1fd9u433aazj20p00k0djc.jpg)
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 enter description here](http://ww4.sinaimg.cn/large/6d132e10jw1fd9u81ztnuj20940ghdia.jpg)
1488537641166.jpg
3. 修改HelpPageConfig.cs
中的代码。
![1488537734229.jpg enter description here](http://ww2.sinaimg.cn/large/6d132e10jw1fd9u9nqxeej214907879l.jpg)
1488537734229.jpg
做完以上设置后,大功告成。妹子,现在我们可以出去玩啦!!!
咦,妹子人呢?