Nswag C# (Wie es für Entwickler funktioniert)

Einführung

APIs sind in der heutigen Softwareentwicklungsumgebung unerlässlich, da sie die Kommunikation zwischen verschiedenen Softwaresystemen und -komponenten erleichtern. Damit Entwickler APIs effizient nutzen können, müssen gründliche und verständliche Dokumente vorhanden sein. Zwei effektive Tools, die den Arbeitsablauf der C#-API-Dokumentation unterstützen können, sind NSwag c# und IronPDF. In diesem Beitrag wird erörtert, wie man mit NSwag die API specs mit .NET Core und erstellen Sie mit IronPDF hochwertige PDF-Dokumente aus diesen Spezifikationen.

Verwendung von NSwag in C##

1. Erstellen Sie eine Restful Web API mit Swagger UI.

2. Erstellen Sie eine C#-Konsolenanwendung.

3. Installieren Sie die NSwag-Bibliothek.

4. Importieren Sie den Namespace und erstellen Sie das Objekt.

5. Verarbeiten Sie das Swagger-JSON in C#-Code.

6. Führen Sie den Code aus und zeigen Sie das Ergebnis an.

Den NSwag verstehen

Eine .NET Swagger-Toolchain namens NSwag wurde entwickelt, um die Erstellung von Swagger-Spezifikationen oder OpenAPI-Dokumenten für APIs zu erleichtern, die mit ASP.NET Web API, ASP.NET Core oder anderen .NET-Frameworks erstellt wurden.

Merkmale von NSwag

Produktion von Swagger specs

Controller, Modelle und .NET-Assemblies können alle von NSwag verwendet werden, um automatisch Swagger-Spezifikationen zu erstellen. NSwag erstellt eine umfassende Dokumentation, die API-Endpunkte, Anfrage-/Antwortformulare, Authentifizierungstechniken und vieles mehr abdeckt, indem die Struktur des API-Codes untersucht wird.

Konnektivität zu .NET-Projekten

Entwickler können die Swagger-Generierung einfach in ihre Entwicklungsprozesse integrieren, indem sie NSwag in .NET-Projekte einbinden. Entwickler können sicherstellen, dass die Dokumentation mit der Codebasis aktualisiert wird, indem sie NSwag zu einem .NET Core-Projekt hinzufügen, das bei jeder Erstellung des Projekts automatisch Swagger-Spezifikationen erstellt.

Personalisierung und Erweiterung

Mit den vielfältigen Anpassungsmöglichkeiten, die NSwag bietet, können Entwickler die generierten Swagger-Spezifikationen leicht an ihre individuellen Bedürfnisse anpassen. Die Entwickler haben über Konfigurationseinstellungen und Anmerkungen die Kontrolle über viele Komponenten der generierten Dokumentation, einschließlich Antwortcodes, Parametererklärungen und Benennungskonventionen für Routen.

Erste Schritte mit Nswag

Einrichten von Nswag in C# Konsolenanwendung

Die Nswag-Basisklassenbibliothek umfasst den Kern-, den Anmerkungs- und den Codegenerierungs-Namensraum, die durch Installation von Nuget verfügbar sein sollten. NSwag in eine C#-Anwendung zu integrieren, um Code und Swagger-Spezifikationen zu generieren, und wie NSwag die Effizienz des Entwicklungsprozesses verbessern kann.

Implementierung von Nswag in der Windows-Konsole und in Formularen

Durch die automatische Client-Generierung können Entwickler effizient Code für den Zugriff auf APIs direkt aus ihren Desktop-Anwendungen heraus erstellen, indem sie NSwag in eine Windows-Desktop-Anwendung integrieren. Bei der Entwicklung von Desktop-Anwendungen, die mit Online-Diensten oder RESTful-APIs kommunizieren, kann dies sehr hilfreich sein.

NSwag kann in Webanwendungen verwendet werden, um API-Dokumentation für interne APIs und Client-Code für die Nutzung externer APIs zu erstellen. Dies hilft Entwicklern dabei, die Frontend- und Backend-Komponenten ihrer Anwendungen konsistent zu halten.

Nswag C# Beispiel

Hier ist ein Codebeispiel, das Ihnen zeigt, wie Sie mit NSwag C#-Client-Code erzeugen können:

using NSwag.CodeGeneration.CSharp;
using NSwag;
using System.Reflection;
using System.CodeDom.Compiler;
using Microsoft.CodeAnalysis;
class Program
{
    static async Task Main(string[] args)
    {
        System.Net.WebClient wclient = new System.Net.WebClient();
        // create json file data from the swagger net core web api
        var document = await OpenApiDocument.FromJsonAsync(wclient.DownloadString("http://localhost:5013/swagger/v1/swagger.json"));
        wclient.Dispose();
        var settings = new CSharpClientGeneratorSettings
        {
            ClassName = "Weather",
            CSharpGeneratorSettings =
    {
        Namespace = "Demo"
    }
        };
        var generator = new CSharpClientGenerator(document, settings);
        var code = generator.GenerateFile();
        var assembly = CompileCode(code);
        var clientType = assembly.GetType("Demo.WeatherClient"); // Replace with your actual client class name
        var httpClient = new HttpClient();
        var client = (IApiClient)Activator.CreateInstance(clientType, httpClient);
        var result = await client.GetWeatherForecastAsync();
        foreach (var item in result)
        {
            Console.WriteLine($"Date: {item.Date} F: {item.TemperatureF} C: {item.TemperatureC} Summary: {item.Summary}");
        }
    }
    static Assembly CompileCode(string code)
    {
        using (var memoryStream = new MemoryStream())
        {
            var assemblyPath = Path.GetDirectoryName(typeof(object).Assembly.Location);
            List<MetadataReference> references = new List<MetadataReference>();
            references.Add(MetadataReference.CreateFromFile(typeof(object).GetTypeInfo().Assembly.Location));
            references.Add(MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "Microsoft.AspNetCore.Mvc.dll")));
            references.Add(MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "System.Web.Http.dll")));
            var compilation = Microsoft.CodeAnalysis.CSharp.CSharpCompilation.Create("ApiClient")
                .AddReferences(Microsoft.CodeAnalysis.MetadataReference.CreateFromFile(typeof(object).Assembly.Location))
                .AddSyntaxTrees(Microsoft.CodeAnalysis.CSharp.SyntaxFactory.ParseSyntaxTree(code)).AddReferences(references);
            var emitResult = compilation.Emit(memoryStream);
            if (!emitResult.Success)
            {
                var diagnostics = emitResult.Diagnostics;
                Console.WriteLine("Compilation errors:");
                foreach (var diagnostic in diagnostics)
                {
                    Console.WriteLine(diagnostic);
                }
                return null;
            }
            memoryStream.Seek(0, SeekOrigin.Begin);
            return Assembly.Load(memoryStream.ToArray());
        }
    }
    public interface IApiClient
    {
        Task<List<WeatherForecast>> GetWeatherForecastAsync(); // Replace with your actual method name and return type
    }
    public class WeatherForecast
    {
        public DateTime Date { get; set; }
        public int TemperatureC { get; set; }
        public int TemperatureF { get; set; }
        public string Summary { get; set; }
    }
}

using NSwag.CodeGeneration.CSharp;
using NSwag;
using System.Reflection;
using System.CodeDom.Compiler;
using Microsoft.CodeAnalysis;
class Program
{
    static async Task Main(string[] args)
    {
        System.Net.WebClient wclient = new System.Net.WebClient();
        // create json file data from the swagger net core web api
        var document = await OpenApiDocument.FromJsonAsync(wclient.DownloadString("http://localhost:5013/swagger/v1/swagger.json"));
        wclient.Dispose();
        var settings = new CSharpClientGeneratorSettings
        {
            ClassName = "Weather",
            CSharpGeneratorSettings =
    {
        Namespace = "Demo"
    }
        };
        var generator = new CSharpClientGenerator(document, settings);
        var code = generator.GenerateFile();
        var assembly = CompileCode(code);
        var clientType = assembly.GetType("Demo.WeatherClient"); // Replace with your actual client class name
        var httpClient = new HttpClient();
        var client = (IApiClient)Activator.CreateInstance(clientType, httpClient);
        var result = await client.GetWeatherForecastAsync();
        foreach (var item in result)
        {
            Console.WriteLine($"Date: {item.Date} F: {item.TemperatureF} C: {item.TemperatureC} Summary: {item.Summary}");
        }
    }
    static Assembly CompileCode(string code)
    {
        using (var memoryStream = new MemoryStream())
        {
            var assemblyPath = Path.GetDirectoryName(typeof(object).Assembly.Location);
            List<MetadataReference> references = new List<MetadataReference>();
            references.Add(MetadataReference.CreateFromFile(typeof(object).GetTypeInfo().Assembly.Location));
            references.Add(MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "Microsoft.AspNetCore.Mvc.dll")));
            references.Add(MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "System.Web.Http.dll")));
            var compilation = Microsoft.CodeAnalysis.CSharp.CSharpCompilation.Create("ApiClient")
                .AddReferences(Microsoft.CodeAnalysis.MetadataReference.CreateFromFile(typeof(object).Assembly.Location))
                .AddSyntaxTrees(Microsoft.CodeAnalysis.CSharp.SyntaxFactory.ParseSyntaxTree(code)).AddReferences(references);
            var emitResult = compilation.Emit(memoryStream);
            if (!emitResult.Success)
            {
                var diagnostics = emitResult.Diagnostics;
                Console.WriteLine("Compilation errors:");
                foreach (var diagnostic in diagnostics)
                {
                    Console.WriteLine(diagnostic);
                }
                return null;
            }
            memoryStream.Seek(0, SeekOrigin.Begin);
            return Assembly.Load(memoryStream.ToArray());
        }
    }
    public interface IApiClient
    {
        Task<List<WeatherForecast>> GetWeatherForecastAsync(); // Replace with your actual method name and return type
    }
    public class WeatherForecast
    {
        public DateTime Date { get; set; }
        public int TemperatureC { get; set; }
        public int TemperatureF { get; set; }
        public string Summary { get; set; }
    }
}

Imports NSwag.CodeGeneration.CSharp
Imports NSwag
Imports System.Reflection
Imports System.CodeDom.Compiler
Imports Microsoft.CodeAnalysis
Friend Class Program
	Shared Async Function Main(ByVal args() As String) As Task
		Dim wclient As New System.Net.WebClient()
		' create json file data from the swagger net core web api
		Dim document = Await OpenApiDocument.FromJsonAsync(wclient.DownloadString("http://localhost:5013/swagger/v1/swagger.json"))
		wclient.Dispose()
		Dim settings = New CSharpClientGeneratorSettings With {
			.ClassName = "Weather",
			.CSharpGeneratorSettings = { [Namespace] = "Demo" }
		}
		Dim generator = New CSharpClientGenerator(document, settings)
		Dim code = generator.GenerateFile()
		Dim assembly = CompileCode(code)
		Dim clientType = assembly.GetType("Demo.WeatherClient") ' Replace with your actual client class name
		Dim httpClient As New HttpClient()
		Dim client = DirectCast(Activator.CreateInstance(clientType, httpClient), IApiClient)
		Dim result = Await client.GetWeatherForecastAsync()
		For Each item In result
			Console.WriteLine($"Date: {item.Date} F: {item.TemperatureF} C: {item.TemperatureC} Summary: {item.Summary}")
		Next item
	End Function
	Private Shared Function CompileCode(ByVal code As String) As System.Reflection.Assembly
		Using memoryStream As New MemoryStream()
			Dim assemblyPath = Path.GetDirectoryName(GetType(Object).Assembly.Location)
			Dim references As New List(Of MetadataReference)()
			references.Add(MetadataReference.CreateFromFile(GetType(Object).GetTypeInfo().Assembly.Location))
			references.Add(MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "Microsoft.AspNetCore.Mvc.dll")))
			references.Add(MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "System.Web.Http.dll")))
			Dim compilation = Microsoft.CodeAnalysis.CSharp.CSharpCompilation.Create("ApiClient").AddReferences(Microsoft.CodeAnalysis.MetadataReference.CreateFromFile(GetType(Object).Assembly.Location)).AddSyntaxTrees(Microsoft.CodeAnalysis.CSharp.SyntaxFactory.ParseSyntaxTree(code)).AddReferences(references)
			Dim emitResult = compilation.Emit(memoryStream)
			If Not emitResult.Success Then
				Dim diagnostics = emitResult.Diagnostics
				Console.WriteLine("Compilation errors:")
				For Each diagnostic In diagnostics
					Console.WriteLine(diagnostic)
				Next diagnostic
				Return Nothing
			End If
			memoryStream.Seek(0, SeekOrigin.Begin)
			Return System.Reflection.Assembly.Load(memoryStream.ToArray())
		End Using
	End Function
	Public Interface IApiClient
		Function GetWeatherForecastAsync() As Task(Of List(Of WeatherForecast)) ' Replace with your actual method name and return type
	End Interface
	Public Class WeatherForecast
		Public Property [Date]() As DateTime
		Public Property TemperatureC() As Integer
		Public Property TemperatureF() As Integer
		Public Property Summary() As String
	End Class
End Class

Für die API, die wir verwenden möchten, geben wir die URL der Swagger-Spezifikation an (swaggerUrl). Dann wird der generierte und ausgeführte Client-Code in einer DLL-Assembly definiert. openApiDocument" verwendet wird. Um das Swagger-Dokument asynchron von der angegebenen URL zu laden, verwenden Sie FromJsonAsync. Um den generierten Client-Code zu ändern, passen wir die Einstellungen des Codegenerators an (cSharpClientGeneratorEinstellungen). In diesem Beispiel werden der Klassenname und der Namespace des erzeugten Client-Codes angegeben.

Aus dem geladenen Swagger-Dokument konstruieren wir eine Instanz von CSharpClientGenerator und verwenden sie, um den Client-Code zu erzeugen (kundencode). Der erstellte Client-Code wird in dem angegebenen Ausgabepfad gespeichert. Wir reagieren auf alle Ausnahmen oder Fehler, die während des Verfahrens auftreten können, und zeigen die entsprechenden Meldungen auf der Konsole an.

NSwag Betrieb

Client-Code generieren

NSwag kann eine Swagger-Spezifikation verwenden, um Client-Code in vielen Sprachen zu generieren, darunter Java, TypeScript und C#. Dies macht es für Entwickler einfach, APIs in ihren Anwendungen zu verwenden.

Erzeugen von Server-Code

Auf der Grundlage einer Swagger-Spezifikation kann NSwag auch Servercode erzeugen, z. B. ASP.NET Core-Controller. Dies hilft, serverseitigen Code für API-Implementierungen schnell zu erstellen.

Erstellung einer interaktiven API-Dokumentation

Ausgehend von einer Swagger-Spezifikation kann NSwag eine interaktive API-Dokumentation, z. B. Swagger UI, erstellen. Diese Dokumentation bietet eine einfach zu verwendende Schnittstelle für die Untersuchung und den Test von API-Endpunkten.

Erzeugen von Proxy-Klassen

Zur Integration mit SOAP-basierten APIs kann NSwag Proxy-Klassen erzeugen. Dies ermöglicht es Programmierern, produzierten Client-Code für den Zugriff auf SOAP-Dienste innerhalb ihrer Anwendungen zu verwenden.

Überprüfung der Swagger-Spezifikationen

NSwag ist in der Lage, Swagger-Spezifikationen zu verifizieren, um sicherzustellen, dass sie dem OpenAPI/Swagger-Standard entsprechen. Dadurch wird es einfacher, Fehler oder Unstimmigkeiten in der API-Dokumentation zu erkennen.

Integration von NSwag in IronPDF

Entwickler können den Arbeitsablauf für API-Dokumentation verbessern, indem sie die Vorteile beider Technologien durch die Integration von NSwag mit IronPDF nutzen. Entwickler können mit NSwag zur Erstellung von Swagger-Spezifikationen und IronPDF zur Umwandlung in das PDF-Format gründliche, offline-fähige Net-Web-API-Dokumentation erstellen, die leicht verfügbar ist und weitergegeben werden kann dokumentation. Die folgenden Verfahren sind Teil des Integrationsprozesses:

IronPDF installieren

• Starten Sie das Visual Studio-Projekt.
• Wählen Sie "Werkzeuge" > "NuGet Package Manager" > "Package Manager Console".
• Öffnen Sie die Eingabeaufforderung und geben Sie in der Paketmanager-Konsole den folgenden Befehl ein:

Install-Package IronPdf

• Alternativ können Sie IronPDF auch mit dem NuGet Package Manager for Solutions installieren.

• Man kann das IronPDF-Paket aus den Suchergebnissen heraussuchen und auswählen und dann auf die Option "Installieren" klicken. Visual Studio übernimmt den Download und die Installation für Sie.

  

• NuGet installiert das IronPDF-Paket und alle für Ihr Projekt erforderlichen Abhängigkeiten.
• Nach der Installation kann IronPDF für Ihr Projekt verwendet werden.

Installation über die NuGet-Website

Weitere Informationen zu den Funktionen, der Kompatibilität und den verfügbaren Downloads von IronPDF finden Sie auf der NuGet-Website unter https://www.nuget.org/packages/IronPdf.

DLL zur Installation verwenden

Alternativ können Sie IronPDF auch direkt in Ihr Projekt einbinden, indem Sie die DLL-Datei verwenden. Um die ZIP-Datei mit der DLL herunterzuladen, klicken Sie hier link. Entpacken Sie die Datei und fügen Sie die DLL zu Ihrem Projekt hinzu.

So erhalten Sie die ZIP-Datei, die die DLL enthält. Nach dem Entpacken binden Sie die DLL in Ihr Projekt ein.

Umsetzung der Logik

Durch den Einsatz von NSwag können Entwickler mit Hilfe von CodeGeneration.CSharp in Verbindung mit IronPDF schneller API-Dokumentation und Client-Code für die Nutzung von APIs erstellen. Die folgenden Schritte sind Teil des Integrationsworkflows:

1. Generierung von Client-Code: Um C#-Client-Code aus Swagger-Spezifikationen zu erstellen, verwenden Sie NSwag.CodeGeneration.CSharp. Die Erstellung von Client-Klassen und Methoden für die Kommunikation mit den API-Endpunkten wird in diesem Schritt automatisiert.

2. NSwag für GetData verwenden: Um JSON-Dokumentation aus Swagger-Spezifikationen zu erstellen, verwenden Sie CodeGeneration.CSharp. In dieser Phase werden die Anfrage-/Antwortformate, Authentifizierungstechniken und API-Client-Endpunkte in eine für Menschen lesbare Dokumentation umgewandelt.

3. JSON in PDF konvertieren: Um das generierte Codeergebnis in ein PDF-Dokument zu konvertieren, verwenden Sie IronPDF. In dieser Phase wird der HTML-Text in ein ausgefeiltes PDF-Dokument umgewandelt, das für die Weitergabe und Verteilung bereit ist.

4. Verbesserung der PDF-Dokumentation: Fügen Sie der PDF-Dokumentation mit IronPDF weitere Inhalte hinzu, z. B. Kopf- und Fußzeilen, Wasserzeichen oder eindeutige Kennzeichnungen. In dieser Phase können die Entwickler das Erscheinungsbild und das Branding der PDF-Dokumentation nach ihrem Geschmack gestalten.

using IronPdf;        
StringBuilder sb = new StringBuilder();

foreach (var item in result)
{
    sb.Append($"<p>Date: {item.Date} F: {item.TemperatureF} C: {item.TemperatureC} Summary: {item.Summary}</p>");
}
var Renderer = new IronPdf.HtmlToPdf();
var PDF = Renderer.RenderHtmlAsPdf(sb.ToString());
// Save PDF to file
PDF.SaveAs("output.pdf");
Console.WriteLine("PDF generated successfully!");
Console.ReadKey();

using IronPdf;        
StringBuilder sb = new StringBuilder();

foreach (var item in result)
{
    sb.Append($"<p>Date: {item.Date} F: {item.TemperatureF} C: {item.TemperatureC} Summary: {item.Summary}</p>");
}
var Renderer = new IronPdf.HtmlToPdf();
var PDF = Renderer.RenderHtmlAsPdf(sb.ToString());
// Save PDF to file
PDF.SaveAs("output.pdf");
Console.WriteLine("PDF generated successfully!");
Console.ReadKey();

Imports IronPdf
Private sb As New StringBuilder()

For Each item In result
	sb.Append($"<p>Date: {item.Date} F: {item.TemperatureF} C: {item.TemperatureC} Summary: {item.Summary}</p>")
Next item
Dim Renderer = New IronPdf.HtmlToPdf()
Dim PDF = Renderer.RenderHtmlAsPdf(sb.ToString())
' Save PDF to file
PDF.SaveAs("output.pdf")
Console.WriteLine("PDF generated successfully!")
Console.ReadKey()

Der obige Code greift auf die aus dem Ergebnisobjekt abgerufenen Daten zu und fügt die Felder "Datum", "TemperaturF", "TemperaturC" und "Zusammenfassung" in einer Schleife an Absätze an. Anschließend gibt er den Pfad der Ausgabedatei für die PDF-Datei an und benachrichtigt den Benutzer, dass eine PDF-Datei erfolgreich erzeugt wurde.

Nachfolgend sehen Sie das Ergebnis des obigen Codes.

Schlussfolgerung

codeGeneration" NSwag-Technologien wie "CSharp" und IronPDF arbeiten gut zusammen, um die Produktion von Client-Code und API-Dokumentation zu rationalisieren. Entwickler können die Erstellung von API-gesteuerten Lösungen beschleunigen, die Erstellung von API-Dokumentation automatisieren und professionell aussehende PDF-Publikationen erstellen, indem sie diese Werkzeuge in C#-Anwendungen integrieren. nSwag.CodeGeneration.CSharp" mit IronPDF bietet Entwicklern eine Komplettlösung für die effiziente Dokumentation von APIs und die Erstellung von Client-Code in C#, unabhängig davon, ob sie Desktop-, Web- oder Cloud-basierte Anwendungen entwickeln.

Das $749 Lite-Paket enthält eine unbefristete Lizenz, ein Jahr Software-Wartung und ein Upgrade der Bibliothek. IronPDF bietet eine kostenlose Lizenz mit zeitlichen und räumlichen Beschränkungen für die Weitergabe an. Die Benutzer können die Lösung während der Testphase ohne Wasserzeichen testen. Weitere Informationen zu Preis und Lizenz finden Sie unter IronPDFs Lizenzierung seite. Auf dieser Seite finden Sie weitere Informationen über Iron Software bibliotheken.