¿Cómo puede Xml Documentation for Web Api incluir documentación más allá del proyecto principal?

La documentación para habilitar la integración de XmlDoc en sus proyectos Web Api parece solo manejar situaciones en las que todos sus tipos de API son parte de su proyecto WebApi. En particular, analiza cómo redirigir la documentación XML App_Data/XmlDocument.xmly descomentar una línea en su configuración que consumirá ese archivo. Esto implícitamente solo permite el archivo de documentación de un proyecto.

Sin embargo, en mi configuración tengo mis tipos de solicitud y respuesta definidos en un proyecto común de "Modelos". Esto significa que si tengo un punto final definido como:

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

Donde OpenIdLoginRequestse define en un proyecto C # separado así:

public class OpenIdLoginRequest
{
    /// <summary>
    /// Represents the OpenId provider that authenticated the user. (i.e. Facebook, Google, etc.)
    /// </summary>
    [Required]
    public string Provider { get; set; }

    ...
}

A pesar de los comentarios de los requestdocumentos XML, las propiedades del parámetro no contienen documentación cuando visualiza la página de ayuda específica del punto final (es decir http://localhost/Help/Api/POST-auth-openid-login).

¿Cómo puedo hacer que los tipos de subproyectos con documentación XML aparezcan en la documentación XML de la API web?

No hay una forma incorporada de lograr esto. Sin embargo, solo requiere unos pocos pasos:

1. Habilite la documentación XML para su subproyecto (desde las propiedades / compilación del proyecto) como lo hizo para su proyecto de API web. Excepto que esta vez, enrutelo directamente para XmlDocument.xmlque se genere en la carpeta raíz de su proyecto.

2. Modifique el evento posterior a la compilación de su proyecto de API web para copiar este archivo XML en su App_Datacarpeta:

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

   Dónde Subproject.xmldebería cambiarse el nombre a cualquiera que sea el nombre de su proyecto plus .xml.

3. A continuación, abra Areas\HelpPage\App_Start\HelpPageConfigy busque la siguiente línea:

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

   Esta es la línea que inicialmente descomentó para habilitar la documentación de ayuda XML en primer lugar. Reemplaza esa línea con:

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

   Este paso asegura que XmlDocumentationProviderse pasa el directorio que contiene sus archivos XML, en lugar del archivo XML específico para su proyecto.

4. Finalmente, modifique Areas\HelpPage\XmlDocumentationProviderde las siguientes formas:

   a. Reemplazar el _documentNavigatorcampo con:

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

   si. Reemplaza el constructor con:

   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. Agregue el siguiente método debajo del constructor:

   private XPathNavigator SelectSingleNode(string selectExpression)
   {
       foreach (var navigator in _documentNavigators)
       {
           var propertyNode = navigator.SelectSingleNode(selectExpression);
           if (propertyNode != null)
               return propertyNode;
       }
       return null;
   }

   re. Y por último, corrija todos los errores del compilador (debería haber tres) que resulten en referencias _documentNavigator.SelectSingleNodey elimine la _documentNavigator.parte para que ahora llame al nuevo SelectSingleNodemétodo que definimos anteriormente.

Este último paso es lo que modifica el proveedor de documentos para admitir la búsqueda en varios documentos XML para el texto de ayuda en lugar de solo el proyecto principal.

Ahora, cuando examine su documentación de ayuda, incluirá documentación XML de los tipos de su proyecto relacionado.

También me encontré con esto, pero no quería editar ni duplicar el código generado para evitar problemas más adelante.

Sobre la base de las otras respuestas, aquí hay un proveedor de documentación autónomo para múltiples fuentes XML. Simplemente coloque esto en su proyecto:

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

... y habilítelo en su HelpPageConfigcon las rutas a los documentos XML que desee:

config.SetDocumentationProvider(new MultiXmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/Api.xml"), HttpContext.Current.Server.MapPath("~/App_Data/Api.Models.xml")));

Una forma más simplificada de hacer esto es fusionando los archivos xml. Código de ejemplo en mi respuesta a continuación:

Comentarios XML de la página de ayuda de Web Api de más de 1 archivo

aquí proporciono un enlace de respuesta con él, que puede ayudarlo. Puede utilizar fácilmente varios archivos XML para la documentación.

Comentarios XML de la página de ayuda de Web Api de más de 1 archivo

La forma más sencilla de solucionar este problema es crear la carpeta App_Code en el servidor que implementó. Luego copie el XmlDocument.xml que tiene en su carpeta bin localmente en la carpeta App_Code