对于网页API XML文档说明如何可以包括除主要项目文档？ [英] How can Xml Documentation for Web Api include documentation from beyond the main project?

问题描述

的<一个href=\"http://www.asp.net/web-api/overview/creating-web-apis/creating-api-help-pages\">documentation启用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 doccomments，参数请求的属性不包含文档，当您查看特定端点帮助页面（即 HTTP：/ /本地主机/帮助/原料药/ POST-AUTH-OpenID的登录）。

我怎样才能让这个类型与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. 启用您的子项目（从项目属性/编译），如您对您的Web API项目的XML文档。只是这一次，直接路由到 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项目的postbuild事件给这个XML文件复制到你的的App_Data 文件夹：

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

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

其中， Subproject.xml 应更名为任何项目的名字加上的.xml 。

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

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

Next open .Areas.HelpPage.HelpPageConfig 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.

最后，修改 ./地区/ HelpPage / XmlDocumentationProvider 在以下几个方面：

Finally, modify ./Areas/HelpPage/XmlDocumentationProvider in the following ways:

一个。与替换 _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());
    }
}

℃。添加的构造下面下面的方法：

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

Ð。而在去年，修复所有编译器错误（应该有三个），导致引用 _documentNavigator.SelectSingleNode 并删除 _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.

这篇关于对于网页API XML文档说明如何可以包括除主要项目文档？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！