Web Api的Xml文档如何包含主项目之外的文档？

用于将XmlDoc集成到Web Api项目中的文档似乎仅用于处理所有API类型都属于WebApi项目的情况。特别是，它讨论了如何将XML文档重新路由到App_Data/XmlDocument.xml配置中的一行并取消注释该行，该行将占用该文件。这隐含地只允许一个项目的文档文件。

但是，在我的设置中，我的请求和响应类型在常见的“模型”项目中定义。这意味着如果我定义了一个端点，例如：

[Route("auth/openid/login")]
public async Task<AuthenticationResponse> Login(OpenIdLoginRequest request) { ... }

在OpenIdLoginRequest单独的C＃项目中定义where ，如下所示：

public class OpenIdLoginRequest
{
    /// <summary>
    /// Represents the OpenId provider that authenticated the user. (i.e. Facebook, Google, etc.)
    /// </summary>
    [Required]
    public string Provider { get; set; }

    ...
}

尽管有XML文档，但是request当您查看特定于端点的帮助页面（即http://localhost/Help/Api/POST-auth-openid-login）时，该参数的属性不包含任何文档。

如何使带有XML文档的子项目中的类型出现在Web API XML文档中？

没有内置方法可以实现此目的。但是，只需要几个步骤：

1. 像为Web API项目一样，为子项目（从项目属性/构建）启用XML文档。除了这次，将其直接路由到，XmlDocument.xml以便在项目的根文件夹中生成它。

2. 修改您的Web API项目的postbuild事件，以将该XML文件复制到您的App_Data文件夹中：

   copy "$(SolutionDir)SubProject\XmlDocument.xml" "$(ProjectDir)\App_Data\Subproject.xml"

   在何处Subproject.xml应将其重命名为您的项目名称为plus .xml。

3. 接下来打开Areas\HelpPage\App_Start\HelpPageConfig并找到以下行：

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

   这是您最初未注释的行，以便首先启用XML帮助文档。将该行替换为：

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

   此步骤确保XmlDocumentationProvider传递包含您的XML文件的目录，而不是包含项目的特定XML文件的目录。

4. 最后，通过Areas\HelpPage\XmlDocumentationProvider以下方式进行修改：

   一个。将_documentNavigator字段替换为：

   private List<XPathNavigator> _documentNavigators = new List<XPathNavigator>();

   b。将构造函数替换为：

   public XmlDocumentationProvider(string appDataPath)
   {
       if (appDataPath == null)
       {
           throw new ArgumentNullException("appDataPath");
       }
   
       var files = new[] { "XmlDocument.xml", "Subproject.xml" };
       foreach (var file in files)
       {
           XPathDocument xpath = new XPathDocument(Path.Combine(appDataPath, file));
           _documentNavigators.Add(xpath.CreateNavigator());
       }
   }

   C。在构造函数下面添加以下方法：

   private XPathNavigator SelectSingleNode(string selectExpression)
   {
       foreach (var navigator in _documentNavigators)
       {
           var propertyNode = navigator.SelectSingleNode(selectExpression);
           if (propertyNode != null)
               return propertyNode;
       }
       return null;
   }

   d。最后，修复所有编译器错误（应该有三个），导致_documentNavigator.SelectSingleNode对该_documentNavigator.部分的引用并删除该部分，以便它现在调用SelectSingleNode我们上面定义的新方法。

最后一步是修改文档提供程序以支持在多个XML文档中查找帮助文本，而不仅仅是主要项目的内容。

现在，当您检查帮助文档时，它将包括相关项目中类型的XML文档。

我也遇到了这个问题，但是我不想编辑或复制任何生成的代码，以避免以后出现问题。

在其他答案的基础上，这是一个用于多个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.GetResponseDocumentation(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));
    }
}

...并HelpPageConfig使用您想要的XML文档的路径在其中启用它：

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

实现此目的的另一种简化方法是合并xml文件。我下面的答复中的示例代码：

Web Api帮助页面来自1个以上文件的XML注释

在这里，我提供了一个答案链接，可以为您提供帮助。您可以轻松地使用多个XML文件进行文档编制。

Web Api帮助页面来自1个以上文件的XML注释

解决此问题的最简单方法是在部署的服务器上创建App_Code文件夹。然后将本地bin文件夹中的XmlDocument.xml复制到App_Code文件夹中