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

generate documentation c#

Question

La documentation para habilitar la integración de XmlDoc en sus proyectos de Api Web parece solo manejar situaciones donde todos sus tipos de API son parte de su proyecto de WebApi. En particular, analiza cómo redirigir la documentación XML a App_Data/XmlDocument.xml y 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 OpenIdLoginRequest se define en un proyecto separado de C # como ese:

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 documentos XML, las propiedades del parámetro de request no contienen documentación cuando se visualiza la página de ayuda específica del endpoint (es decir, http://localhost/Help/Api/POST-auth-openid-login ).

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

Answer 1

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

Answer 2

Me encontré con esto también, pero no quería editar ni duplicar ninguno de los códigos generados para evitar problemas más adelante.

Sobre la base de las otras respuestas, aquí hay un proveedor de documentación independiente para múltiples fuentes XML. Solo deja esto en tu 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 HelpPageConfig con 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")));

Answer 3

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

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

2. Modifique el evento postbuild de su proyecto de API web para copiar este archivo XML en su carpeta App_Data :

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

   Donde Subproject.xml debe renombrarse como el nombre de su proyecto es más .xml .

3. A continuación, abra Areas/HelpPage/HelpPageConfig y ubique la siguiente línea:

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

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

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

   Este paso garantiza que XmlDocumentationProvider se transfiera al directorio que contiene sus archivos XML, en lugar del archivo XML específico para su proyecto.

4. Finalmente, modifique Areas/HelpPage/XmlDocumentationProvider de las siguientes maneras:

   a. Reemplace el campo _documentNavigator con:

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

   segundo. Reemplace 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());
       }
   }

   do. 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 (debe haber tres), lo que da como resultado referencias a _documentNavigator.SelectSingleNode y elimine el _documentNavigator. porción para que ahora llame al nuevo método SelectSingleNode que definimos anteriormente.

Este último paso es lo que modifica el proveedor de documentos para que permita buscar en varios documentos XML 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 en su proyecto relacionado.

Answer 4

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

Página web de ayuda de API Comentarios de más de 1 archivos

Answer 5

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

Página web de ayuda de API Comentarios de más de 1 archivos