Wie kann die Xml-Dokumentation für Web Api eine Dokumentation von außerhalb des Hauptprojekts enthalten?

Den Dokumentation für die Aktivierung XmlDoc integration in Ihre Web Api-Projekte anscheinend nur mit Situationen umgehen, wo Sie alle Ihre API-Typen sind Teil des WebApi-Projekt. Es behandelt insbesondere, wie die Umleitung der XML-Dokumentation zu App_Data/XmlDocument.xml - und einkommentieren einer Zeile in der config, dass verbrauchen wird die Datei. Diese implizit erlaubt nur eine Projekt-Dokumentation Datei.

Allerdings in meinem setup habe ich meine Anfrage-und Antwort-Typen in einem gemeinsamen "Modelle" - Projekt. Dies bedeutet, dass, wenn ich einen Endpunkt definiert, wie:

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

Wo OpenIdLoginRequest definiert ist, in einer separaten C# - Projekt so:

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-doccomments, die Eigenschaften der request parameter enthalten keine Dokumentation, die beim anzeigen der Endpunkt-spezifische Hilfe-Seite (d.h. http://localhost/Help/Api/POST-auth-openid-login).

Wie kann ich es so machen, dass die Typen in den Teilprojekten mit der XML-Dokumentation sind aufgetaucht in der Web-API XML-Dokumentation?

InformationsquelleAutor der Frage Kirk Woll | 2014-02-19

  1. 149

    Gibt es keine integrierte Möglichkeit, dies zu erreichen. Jedoch, es erfordert nur wenige Schritte:

    1. Ermöglichen, XML-Dokumentation, die für Ihr Teilprojekt (von der Projekt-Eigenschaften /erstellen), wie Sie für Ihre Web-API-Projekt. Außer dieser Zeit, führen Sie es direkt auf XmlDocument.xml so, es wird erzeugt im Projekt - root-Ordner.

    2. Ändern Sie Ihre Web-API-Projekt ist postbuild-Ereignis kopieren Sie diese XML-Datei in Ihr App_Data Ordner:

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

      Wo Subproject.xml sollte umbenannt werden, was auch immer Ihr Projekt, der name ist plus .xml.

    3. Nächsten öffnen Areas\HelpPage\HelpPageConfig und suchen Sie die folgende Zeile:

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

      Dies ist die Zeile, die Sie zunächst unkommentiert, um zu ermöglichen, XML-Dokumentation in den ersten Platz. Ersetzen Sie diese Zeile mit:

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

      Dieser Schritt stellt sicher, dass XmlDocumentationProvider übergeben wird das Verzeichnis mit der XML-Dateien, anstatt die spezifische XML-Datei für das Projekt.

    4. Schließlich ändern Areas\HelpPage\XmlDocumentationProvider haben Sie folgende Möglichkeiten:

      ein. Ersetzen Sie die _documentNavigator Feld mit:

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

      b. Ersetzen Sie den Konstruktor mit:

      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 unten Konstruktor:

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

      d. Und letzten, Update alle compiler-Fehler (sollte es drei), die sich in Referenzen zu _documentNavigator.SelectSingleNode und entfernen Sie die _documentNavigator. Teil, so dass es nun nennt sich die neue SelectSingleNode Methode, die wir oben definiert.

    Dieser Letzte Schritt ist, was ändert das Dokument Anbieter zur Unterstützung der Suche innerhalb mehrerer XML-Dokumente für die Hilfe, text, anstatt nur die primäre Projekts.

    Nun, wenn Sie prüfen, Ihre Hilfe, Sie wird die XML-Dokumentation von Arten in Ihrem verwandten-Projekt.

    InformationsquelleAutor der Antwort Kirk Woll

  2. 28

    Lief ich in diese auch, aber ich wollte nicht zu Bearbeiten oder duplizieren eine der generierte code später Probleme zu vermeiden.

    Gebäude auf die anderen Antworten, hier eine eigenständige Dokumentation-provider für mehrere XML-Quellen. Legen Sie einfach diese in Ihr Projekt:

    ///<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 HelpPageConfig die Pfade zu der XML-Dokumente, die Sie wollen:

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

    InformationsquelleAutor der Antwort Pathoschild

  3. 5

    Eine einfachere Methode, dies zu tun ist durch die Zusammenführung der xml-Dateien. Beispiel-code in meiner Antwort unten:

    Web-Api-Hilfe Seite, die XML-Kommentare von mehr als 1 Dateien

    InformationsquelleAutor der Antwort Kiran Challa

  4. 0

    hier biete ich einen Antwort-link, die Ihnen helfen können.
    Sie können leicht mit mehreren XML-Datei für die Dokumentation.

    Web-Api-Hilfe Seite, die XML-Kommentare von mehr als 1 Dateien

    InformationsquelleAutor der Antwort shekhar patel

  5. 0

    Einfachste Weg, um dieses Problem zu beheben ist, erstellen Sie die App_Code-Ordner auf dem server Sie implementiert. Kopieren Sie dann die XmlDocument.xml Sie haben in Ihrem bin Ordner lokal in den Ordner App_Code

    InformationsquelleAutor der Antwort Ziregbe Otee

Schreibe einen Kommentar