Question

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

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

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

其中OpenIdLoginRequest在单独的C＃项目中定义如下：

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参数的属性不包含任何文档。

如何在Web API XML文档中显示带有XML文档的子项目中的类型？

Answer 1

没有内置的方法来实现这一目标。但是，它只需要几个步骤：

为您的子项目启用XML文档（来自项目属性/构建），就像您对Web API项目一样。除此之外，将其直接路由到XmlDocument.xml，以便在项目的根文件夹中生成。
修改Web API项目的postbuild事件，将此XML文件复制到App_Data文件夹中：
```
copy "$(SolutionDir)SubProject\XmlDocument.xml" "$(ProjectDir)\App_Data\Subproject.xml"
```
Subproject.xml应重命名为您的项目名称加上.xml。
接下来打开Areas\HelpPage\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文件。

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

一个。将_documentNavigator字段替换为：

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

湾用以下内容替换构造函数：

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());
    }
}

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

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文档。

Answer 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.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")));

Answer 3

另一种简化的方法是合并xml文件。我在下面的回复中的示例代码：

Web Api Help Page XML comments from more than 1 files

Answer 4

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

Answer 5

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

Web Api Help Page XML comments from more than 1 files

Answer 6

我找到了更好的解决方案

转到解决方案的属性，然后在“内置，输出，文档XML文件”上填充应用数据中的文件夹。
将要插入文件的行添加到这样的文档中。

config.SetDocumentationProvider（new XmlDocumentationProvider（ HttpContext.Current.Server.MapPath（“〜/ App_Data / FenixCorporate.API.xml”））））;

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

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

6 个答案: