In che modo la documentazione Xml per Web Api può includere documentazione oltre il progetto principale?

La documentazione per abilitare l'integrazione XmlDoc nei tuoi progetti Web Api sembra gestire solo le situazioni in cui tutti i tuoi tipi di API fanno parte del tuo progetto WebApi. In particolare, discute come reindirizzare la documentazione XML App_Data/XmlDocument.xmle decommentare una riga nella configurazione che consumerà quel file. Ciò consente implicitamente solo il file di documentazione di un progetto.

Tuttavia, nella mia configurazione ho i miei tipi di richiesta e risposta definiti in un progetto "Modelli" comune. Ciò significa che se ho un endpoint definito come:

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

Where OpenIdLoginRequestè definito in un progetto C # separato in questo modo:

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

    ...
}

Nonostante i doccomments XML, le proprietà del requestparametro non contengono documentazione quando si visualizza la pagina della guida specifica dell'endpoint (cioè http://localhost/Help/Api/POST-auth-openid-login).

Come posso fare in modo che i tipi nei sottoprogetti con documentazione XML vengano visualizzati nella documentazione XML dell'API Web?

Non esiste un modo integrato per ottenere questo risultato. Tuttavia, richiede solo pochi passaggi:

1. Abilita la documentazione XML per il tuo sottoprogetto (dalle proprietà / build del progetto) come hai fatto per il tuo progetto API Web. Tranne questa volta, indirizzalo direttamente a in XmlDocument.xmlmodo che venga generato nella cartella principale del tuo progetto.

2. Modifica l'evento post-compilazione del tuo progetto API Web per copiare questo file XML nella tua App_Datacartella:

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

   Dove Subproject.xmldovrebbe essere rinominato qualunque sia il nome del progetto più .xml.

3. Quindi apri Areas\HelpPage\App_Start\HelpPageConfige individua la riga seguente:

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

   Questa è la riga che inizialmente hai decommentato per abilitare la documentazione della guida XML in primo luogo. Sostituisci quella riga con:

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

   Questo passaggio garantisce che XmlDocumentationProvidervenga passata la directory che contiene i file XML, anziché il file XML specifico per il progetto.

4. Infine, modifica Areas\HelpPage\XmlDocumentationProvidernei seguenti modi:

   un. Sostituisci il _documentNavigatorcampo con:

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

   b. Sostituisci il costruttore 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. Aggiungi il seguente metodo sotto il costruttore:

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

   d. Infine, correggi tutti gli errori del compilatore (dovrebbero essercene tre) risultanti in riferimenti _documentNavigator.SelectSingleNodee rimuovi la _documentNavigator.parte in modo che ora chiami il nuovo SelectSingleNodemetodo che abbiamo definito sopra.

Questo ultimo passaggio è ciò che modifica il fornitore del documento per supportare la ricerca all'interno di più documenti XML per il testo della guida piuttosto che solo per il progetto principale.

Ora, quando esamini la documentazione della Guida, includerà la documentazione XML dai tipi nel progetto correlato.

Mi sono imbattuto anche in questo, ma non volevo modificare o duplicare il codice generato per evitare problemi in seguito.

Basandosi sulle altre risposte, ecco un fornitore di documentazione autonomo per più origini XML. Inseriscilo nel tuo progetto:

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

... e abilitalo nel tuo HelpPageConfigcon i percorsi ai documenti XML che desideri:

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

Un altro modo semplificato per farlo è unire i file xml. Codice di esempio nella mia risposta di seguito:

Pagina della guida dell'API Web Commenti XML da più di 1 file

qui fornisco un link di risposta con esso, che può aiutarti. È possibile utilizzare facilmente più file XML per la documentazione.

Pagina della guida dell'API Web Commenti XML da più di 1 file

Il modo più semplice per risolvere questo problema è creare la cartella App_Code sul server che hai distribuito. Quindi copia il XmlDocument.xml che hai nella tua cartella bin localmente nella cartella App_Code