Swagger-Dokumentation mit externen Bibliotheken

Es ist eine gute Sache, mehrere Bibliotheken zu verwenden, um Ihren Code für zukünftige Fälle aufzuteilen. Persönlich mache ich es gerne, wenn ich meine Logik aufteilen kann, damit sie in anderen Projekten oder Teilen von Projekten wiederverwendet werden kann.

Zumindest für mich ist es ein Muss, die Datenmodelle aufzuteilen, einschließlich des Entity Framework, damit es in einem Console application, einem Blazor application oder einem API referenziert und verwendet werden kann.

Werfen wir einen Blick auf ein Beispiel dafür, wie ich Dinge mache. Dies ist ein Screenshot eines Projekts mit einigen Anwendungen und einer gemeinsam genutzten Bibliothek mit allen Modellen.

Dies ist ein Beispiel für eine Klasse, die ich aus dem Projekt API mit Dokumentation mit summary für jede Eigenschaft und Klasse verschoben habe.

namespace CustomLibrariesDocumentation.Models
{
    /// <summary>
    /// WeatherForecast class
    /// </summary>
    public class WeatherForecast
    {
        /// <summary>
        /// Gets or sets the Date
        /// </summary>
        public DateOnly Date { get; set; }

        /// <summary>
        /// Gets or sets the TemperatureC
        /// </summary>
        public int TemperatureC { get; set; }

        /// <summary>
        /// Gets or sets the TemperatureF
        /// </summary>
        public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);

        /// <summary>
        /// Gets or sets the Summary
        /// </summary>
        public string? Summary { get; set; }
    }
}

Wenn wir es auf Console application verweisen und mit der Verwendung des Modells beginnen, können wir die Dokumentation sehen. Das ist eine Standardfunktion in Visual Studio und funktioniert daher einwandfrei, wie Sie hier sehen können:

Aber wenn wir dann auf den API verweisen und zu Swagger gehen, gibt es keine zusammenfassende Dokumentation.

Wie können wir das beheben?

Zuerst müssen wir XML-Kommentare in der Bibliothek aktivieren. Dazu müssen Sie die Projekteinstellungen aktualisieren und Folgendes aktivieren:

Dadurch werden einige Dateien im Build-Ordner generiert, die mit der Dateierweiterung xml enden, wie Sie hier sehen können:

Nachdem wir dies nun erledigt haben, müssen wir einige Dinge zum Program.cs hinzufügen, um diese Dateien lesen zu können. Dies liegt daran, dass standardmäßig nur die XML-Definition des Projekts geladen wird, auf dem es sich befindet.

Es verwendet eine Methode, die wir in AddSwaggerGen haben und die IncludeXmlComments heißt.

Die Idee ist, dass wir, wenn wir alle xml-Dateien haben, das Laden auf den Swagger erzwingen.

builder.Services.AddSwaggerGen(s =>
{
    // Comments
    var allXmlFiles = Directory.GetFiles(AppContext.BaseDirectory, "*.xml");

    foreach (string xmlFiles in allXmlFiles)
    {
        s.IncludeXmlComments(xmlFiles);
    }
});

Es ist ganz einfach: Wir holen die xml-Dateien aus dem Build-Verzeichnis und fügen sie mit der Methode IncludeXmlComments hinzu.

Jetzt laden wir erneut den API und prüfen, ob wir die Dokumentation sehen können.

Und Sie können sehen, dass wir die Dokumentation sehen können!

Ich hoffe, es hat Ihnen geholfen. Wenn Sie Fragen haben, können Sie mich gerne kontaktieren!