Wie kann die XML-Dokumentation für Web-API eine Dokumentation enthalten, die über das Hauptprojekt hinausgeht?

Die Dokumentation zum Aktivieren der XmlDoc-Integration in Ihre Web-Api-Projekte behandelt anscheinend nur Situationen, in denen alle Ihre API-Typen Teil Ihres WebApi-Projekts sind. Insbesondere wird erläutert, wie Sie die XML-Dokumentation in App_Data/XmlDocument.xmleine Zeile in Ihrer Konfiguration umleiten und diese auskommentieren, in der diese Datei verwendet wird. Dies erlaubt implizit nur die Dokumentationsdatei eines Projekts.

In meinem Setup habe ich jedoch meine Anforderungs- und Antworttypen in einem gemeinsamen "Modelle" -Projekt definiert. Dies bedeutet, dass wenn ich einen Endpunkt definiert habe wie:

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

Wo OpenIdLoginRequestist in einem separaten C # -Projekt wie folgt definiert:

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

    ...
}

Trotz der XML-Anweisungen enthalten die Eigenschaften des requestParameters keine Dokumentation, wenn Sie die endpunktspezifische Hilfeseite (dh http://localhost/Help/Api/POST-auth-openid-login) anzeigen .

Wie kann ich dafür sorgen, dass Typen in Teilprojekten mit XML-Dokumentation in der Web-API-XML-Dokumentation auftauchen?

Es gibt keinen eingebauten Weg, um dies zu erreichen. Es sind jedoch nur wenige Schritte erforderlich:

1. Aktivieren Sie die XML-Dokumentation für Ihr Teilprojekt (aus Projekteigenschaften / Build) wie für Ihr Web-API-Projekt. Leiten Sie es außer diesmal direkt an weiter, XmlDocument.xmldamit es im Stammordner Ihres Projekts generiert wird.

2. Ändern Sie das Postbuild-Ereignis Ihres Web-API-Projekts, um diese XML-Datei in Ihren App_DataOrdner zu kopieren :

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

   Wo Subproject.xmlsollte unabhängig von Ihrem Projekt den Namen umbenannt werden plus .xml.

3. Öffnen Sie Areas\HelpPage\App_Start\HelpPageConfigals nächstes die folgende Zeile und suchen Sie sie:

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

   Dies ist die Zeile, die Sie anfangs nicht kommentiert haben, um die XML-Hilfedokumentation überhaupt zu aktivieren. Ersetzen Sie diese Zeile durch:

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

   Dieser Schritt stellt sicher, dass XmlDocumentationProviderdas Verzeichnis übergeben wird, das Ihre XML-Dateien enthält, und nicht die spezifische XML-Datei für Ihr Projekt.

4. Ändern Sie abschließend Areas\HelpPage\XmlDocumentationProviderdie folgenden Methoden:

   ein. Ersetzen Sie das _documentNavigatorFeld durch:

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

   b. Ersetzen Sie den Konstruktor durch:

   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. Fügen Sie die folgende Methode unter dem Konstruktor hinzu:

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

   d. Beheben Sie zuletzt alle Compilerfehler (es sollten drei sein), die zu Verweisen auf _documentNavigator.SelectSingleNodeden _documentNavigator.Teil führen , und entfernen Sie ihn, sodass er jetzt die SelectSingleNodeoben definierte neue Methode aufruft .

Dieser letzte Schritt ändert den Dokumentanbieter so, dass die Suche in mehreren XML-Dokumenten nach dem Hilfetext und nicht nur nach dem primären Projekt unterstützt wird.

Wenn Sie nun Ihre Hilfedokumentation untersuchen, enthält sie XML-Dokumentation von Typen in Ihrem verwandten Projekt.

Ich bin auch darauf gestoßen, wollte aber keinen der generierten Codes bearbeiten oder duplizieren, um später Probleme zu vermeiden.

Aufbauend auf den anderen Antworten finden Sie hier einen eigenständigen Dokumentationsanbieter für mehrere XML-Quellen. Fügen Sie dies einfach in Ihr Projekt ein:

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

... und aktivieren Sie es in Ihrem HelpPageConfigmit den Pfaden zu den gewünschten XML-Dokumenten:

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

Eine weitere vereinfachte Möglichkeit besteht darin, die XML-Dateien zusammenzuführen. Beispielcode in meiner folgenden Antwort:

Web-API-Hilfeseite XML-Kommentare aus mehr als einer Datei

Hier stelle ich einen Antwortlink zur Verfügung, der Ihnen helfen kann. Sie können problemlos mehrere XML-Dateien zur Dokumentation verwenden.

Web-API-Hilfeseite XML-Kommentare aus mehr als einer Datei

Die einfachste Möglichkeit, dieses Problem zu beheben, besteht darin, den Ordner App_Code auf dem von Ihnen bereitgestellten Server zu erstellen. Kopieren Sie dann die XmlDocument.xml, die Sie in Ihrem bin-Ordner haben, lokal in den App_Code-Ordner