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

Question

将XmlDoc集成到Web Api项目中的文档似乎只处理所有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

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

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

2. 修改Web API项目的postbuild事件,将此XML文件复制到您的App_Data文件夹中:

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

   哪里Subproject.xml应该重命名为你的项目名称加上什么.xml.

3. 接下来打开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文件.

4. 最后,通过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());
       }
   }
   

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

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帮助页面来自多个文件的XML注释