目前，我有一个与 ASP.NET Web 应用程序并行运行的 ASP.NET Web Api。使用 Yao Huang 在他与 HelpPage NuGet 包相关的博客文章中概述的方法，特别是XMLDocumentationProvider，我已经成功地记录了我的 API - 几乎......
我遇到的问题是特定的 API 方法调用继承（并可能覆盖）基类的行为，我们将调用它ApiBase。因此，这些方法没有自己的文档，因为它们是从基类继承的方法，通常不需要比ApiBase. 我正在尝试做的（并且没有关于如何做的方向）是，对于从基类继承实现的方法，找到一种方法来继承和显示与基类关联的关联 XML 注释并显示它们与被调用的方法。
为了澄清这一点，这里有一个示例方法ApiBase：
public abstract class ApiBase
{
/// <summary>
/// Stub used as an example
/// </summary>
/// <param name="stub">Random boolean value</param>
/// <returns>The boolean value</returns>
public virtual bool returnBool(bool stub)
{
return stub;
}
/// <summary>
/// Stub #2 used as an example
/// </summary>
/// <param name="stub">Random int value</param>
/// <returns>A value less than the parameter</returns>
public virtual int returnLess(int stub)
{
return (stub - 10);
}
}
稍后，假设我们有一个控制器类 ，ApiChild它继承了这个功能：
public class ApiChild : ApiBase
{
public override int returnLess(int stub)
{
return (stub - 20);
}
}
当ApiChild调用returnBool或returnLess时，我希望他们的评论可以从基类中被XMLDocumentationProvider. ApiExplorer 已经成功地从基类中获取了其余信息，例如返回类型、参数等，但我不确定如何将此功能扩展到评论检索。感谢您提供的任何帮助。我自己的想法倾向于某种实现，它使用反射在运行时分析方法以确定其属性，并在需要时以某种方式适当地从其父级获取注释。非常感谢任何想法/指导。
作为参考，这里是当前使用的代码XMLDocumentationProvider：
using System;
using System.Globalization;
using System.Linq;
using System.Reflection;
using System.Web.Http.Controllers;
using System.Web.Http.Description;
using System.Xml.XPath;
namespace MyProject.Areas.HelpPage
{
public interface IResponseDocumentationProvider
{
string GetResponseDocumentation(HttpActionDescriptor actionDescriptor);
}
/// <summary>
/// A custom <see cref="IDocumentationProvider"/> that reads the API documentation from an XML documentation file.
/// </summary>
public class XmlDocumentationProvider : IDocumentationProvider, IResponseDocumentationProvider
{
private XPathNavigator _documentNavigator;
private const string MethodExpression = "/doc/members/member[@name='M:{0}']";
private const string ParameterExpression = "param[@name='{0}']";
/// <summary>
/// Initializes a new instance of the <see cref="XmlDocumentationProvider"/> class.
/// </summary>
/// <param name="documentPath">The physical path to XML document.</param>
public XmlDocumentationProvider(string documentPath)
{
if (documentPath == null)
{
throw new ArgumentNullException("documentPath");
}
XPathDocument xpath = new XPathDocument(documentPath);
_documentNavigator = xpath.CreateNavigator();
}
public virtual string GetDocumentation(HttpActionDescriptor actionDescriptor)
{
XPathNavigator methodNode = GetMethodNode(actionDescriptor);
if (methodNode != null)
{
XPathNavigator summaryNode = methodNode.SelectSingleNode("summary");
if (summaryNode != null)
{
return summaryNode.Value.Trim();
}
}
return null;
}
public virtual string GetDocumentation(HttpParameterDescriptor parameterDescriptor)
{
ReflectedHttpParameterDescriptor reflectedParameterDescriptor = parameterDescriptor as ReflectedHttpParameterDescriptor;
if (reflectedParameterDescriptor != null)
{
XPathNavigator methodNode = GetMethodNode(reflectedParameterDescriptor.ActionDescriptor);
if (methodNode != null)
{
string parameterName = reflectedParameterDescriptor.ParameterInfo.Name;
XPathNavigator parameterNode = methodNode.SelectSingleNode(String.Format(CultureInfo.InvariantCulture, ParameterExpression, parameterName));
if (parameterNode != null)
{
return parameterNode.Value.Trim();
}
}
}
return null;
}
private XPathNavigator GetMethodNode(HttpActionDescriptor actionDescriptor)
{
ReflectedHttpActionDescriptor reflectedActionDescriptor = actionDescriptor as ReflectedHttpActionDescriptor;
if (reflectedActionDescriptor != null)
{
string selectExpression = String.Format(CultureInfo.InvariantCulture, MethodExpression, GetMemberName(reflectedActionDescriptor.MethodInfo));
return _documentNavigator.SelectSingleNode(selectExpression);
}
return null;
}
private static string GetMemberName(MethodInfo method)
{
string name = String.Format(CultureInfo.InvariantCulture, "{0}.{1}", method.DeclaringType.FullName, method.Name);
ParameterInfo[] parameters = method.GetParameters();
if (parameters.Length != 0)
{
string[] parameterTypeNames = parameters.Select(param => GetTypeName(param.ParameterType)).ToArray();
name += String.Format(CultureInfo.InvariantCulture, "({0})", String.Join(",", parameterTypeNames));
}
return name;
}
private static string GetTypeName(Type type)
{
if (type.IsGenericType)
{
// Format the generic type name to something like: Generic{System.Int32,System.String}
Type genericType = type.GetGenericTypeDefinition();
Type[] genericArguments = type.GetGenericArguments();
string typeName = genericType.FullName;
// Trim the generic parameter counts from the name
typeName = typeName.Substring(0, typeName.IndexOf('`'));
string[] argumentTypeNames = genericArguments.Select(t => GetTypeName(t)).ToArray();
return String.Format(CultureInfo.InvariantCulture, "{0}{{{1}}}", typeName, String.Join(",", argumentTypeNames));
}
return type.FullName;
}
public virtual string GetResponseDocumentation(HttpActionDescriptor actionDescriptor)
{
XPathNavigator methodNode = GetMethodNode(actionDescriptor);
if (methodNode != null)
{
XPathNavigator returnsNode = methodNode.SelectSingleNode("returns");
if (returnsNode != null)
return returnsNode.Value.Trim();
}
return null;
}
}
}