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

一尘不染

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文档中？

阅读 327

2020-05-19

共1个答案

一尘不染

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

像为Web API项目一样，为子项目（从项目属性/构建）启用XML文档。除了这次，将其直接路由到，XmlDocument.xml以便在项目的根文件夹中生成它。
修改Web API项目的postbuild事件以将此XML文件复制到您的App_Data文件夹中：
```
copy "$(SolutionDir)SubProject\XmlDocument.xml" "$(ProjectDir)\App_Data\Subproject.xml"
```

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

接下来打开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文件的目录。

最后，通过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文档。

2020-05-19