Web Api 的 Xml 文档如何包含主项目之外的文档? [英] How can Xml Documentation for Web Api include documentation from beyond the main project?

问题描述

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

The documentation for enabling XmlDoc integration into your Web Api projects appears to only handle situations where all of your API types are part of your WebApi project. In particular, it discusses how to reroute the XML documentation to App_Data/XmlDocument.xml and uncommenting a line in your config that will consume that file. This implicitly only allows for one project's documentation file.

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

However, in my setup I have my request and response types defined in a common "Models" project. This means that if I have an endpoint defined such as:

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

其中 OpenIdLoginRequest 在单独的 C# 项目中定义，如下所示:

Where OpenIdLoginRequest is defined in a separate C# project like so:

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 文档注释，当您查看特定于端点的帮助页面(即 http://localhost/Help/Api/POST-)时，request 参数的属性不包含任何文档auth-openid-login).

Despite the XML doccomments, the properties of the request parameter contain no documentation when you view the endpoint-specific help page (i.e. http://localhost/Help/Api/POST-auth-openid-login).

如何才能使带有 XML 文档的子项目中的类型在 Web API XML 文档中显示?

How can I make it so that types in subprojects with XML documentation are surfaced in the Web API XML documentation?

推荐答案

没有内置的方法来实现这一点.但是，它只需要几个步骤:

There is no built-in way to achieve this. However, it requires only a few steps:

1. 为您的子项目启用 XML 文档(来自项目属性/构建)，就像您为 Web API 项目启用的那样.除了这一次，将它直接路由到 XmlDocument.xml 以便它在项目的根文件夹中生成.

1. Enable XML documentation for your subproject (from project properties / build) like you have for your Web API project. Except this time, route it directly to XmlDocument.xml so that it gets generated in your project's root folder.

修改您的 Web API 项目的构建后事件以将此 XML 文件复制到您的 App_Data 文件夹中:

Modify your Web API project's postbuild event to copy this XML file into your App_Data folder:

copy "$(SolutionDir)SubProjectXmlDocument.xml" "$(ProjectDir)App_DataSubproject.xml"

Subproject.xml 应该重命名为任何你的项目名称加上 .xml.

Where Subproject.xml should be renamed to whatever your project's name is plus .xml.

接下来打开 AreasHelpPageApp_StartHelpPageConfig 并找到以下行:

Next open AreasHelpPageApp_StartHelpPageConfig and locate the following line:

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

这是您最初取消注释的行，以便首先启用 XML 帮助文档.将该行替换为:

This is the line you initially uncommented in order to enable XML help documentation in the first place. Replace that line with:

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

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

This step ensures that XmlDocumentationProvider is passed the directory that contains your XML files, rather than the specific XML file for your project.

最后修改AreasHelpPageXmlDocumentationProvider如下:

一个.将 _documentNavigator 字段替换为:

a. Replace the _documentNavigator field with:

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

B.将构造函数替换为:

b. Replace the constructor with:

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.在构造函数下面添加以下方法:

c. Add the following method below the constructor:

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 的所有编译器错误(应该有 3 个)并删除 _documentNavigator. 部分，以便它现在调用新的 SelectSingleNode 我们在上面定义的方法.

d. And last, fix all compiler errors (there should be three) resulting in references to _documentNavigator.SelectSingleNode and remove the _documentNavigator. portion so that it now calls the new SelectSingleNode method we defined above.

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

This Last step is what modifies the document provider to support looking within multiple XML documents for the help text rather than just the primary project's.

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

Now when you examine your Help documentation, it will include XML documentation from types in your related project.

这篇关于Web Api 的 Xml 文档如何包含主项目之外的文档?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！