API sa niezbedne we wspolczesnym srodowisku tworzenia oprogramowania, poniewaz ulatwiaja komunikacje pomiedzy roznymi systemami i komponentami oprogramowania. Aby programisci mogli efektywnie korzystac z API, konieczna jest szczegolowa i zrozumiala dokumentacja. Dwa skuteczne narzedzia, ktore moga pomoc w pracy nad dokumentacja API w C#, to NSwag C# i IronPDF. W tym artykule omowimy, jak uzywac NSwag do generowania specyfikacji API z .NET Core oraz jak generowac wysokiej jakosci dokumenty PDF z tych specyfikacji z uzyciem IronPDF.
Narzedzie .NET Swagger o nazwie NSwag zostalo stworzone, aby ulatwic tworzenie specyfikacji Swagger, czyli dokumentow OpenAPI, dla API skonstruowanych przy uzyciu ASP.NET Web API, ASP.NET Core lub innych frameworkow .NET.
NSwag może wykorzystywać kontrolery, modele i zestawy .NET do automatycznego generowania specyfikacji Swagger. NSwag generuje kompleksową dokumentację obejmującą punkty końcowe API, formularze żądań/odpowiedzi, techniki uwierzytelniania i wiele innych elementów poprzez analizę struktury kodu API.
Programiści mogą z łatwością włączyć generowanie Swagger do swoich procesów programistycznych poprzez integrację NSwag z projektami .NET. Programiści mogą zapewnić aktualizację dokumentacji wraz z kodem źródłowym, dodając NSwag do projektu .NET Core, co spowoduje automatyczne generowanie specyfikacji Swagger przy każdej kompilacji projektu.
Dzięki szerokiemu zakresowi możliwości dostosowywania oferowanych przez NSwag programiści mogą z łatwością dostosować wygenerowane specyfikacje Swagger do swoich indywidualnych potrzeb. Programiści mają kontrolę nad wieloma elementami generowanej dokumentacji, w tym kodami odpowiedzi, objaśnieniami parametrów i konwencjami nazewnictwa tras, poprzez ustawienia konfiguracyjne i adnotacje.
Biblioteka klas bazowych NSwag zawiera przestrzeń nazw core, Annotation oraz generowania kodu, które powinny być dostępne po zainstalowaniu z NuGet. Jak zintegrować NSwag z aplikacją C# w celu generowania kodu i specyfikacji Swagger oraz w jaki sposób NSwag może poprawić wydajność procesu programowania.
Dzięki automatycznemu generowaniu klientów programiści mogą efektywnie tworzyć kod umożliwiający dostęp do interfejsów API bezpośrednio z poziomu swoich aplikacji desktopowych poprzez integrację NSwag z aplikacją desktopową dla systemu Windows. Może to być bardzo pomocne podczas tworzenia aplikacji desktopowych, które komunikują się z usługami online lub interfejsami API RESTful.
NSwag może być używany w aplikacjach internetowych do generowania dokumentacji API dla wewnętrznych interfejsów API oraz kodu klienckiego do korzystania z zewnętrznych interfejsów API. Pomaga to programistom w utrzymaniu spójności komponentów frontendowych i backendowych ich aplikacji.
Oto przykład kodu pokazujący, jak używać NSwag do generowania kodu klienta w języku C#:
using NSwag.CodeGeneration.CSharp;
using NSwag;
using System.Reflection;
using System.CodeDom.Compiler;
using Microsoft.CodeAnalysis;
using System.Net.Http;
using System.IO;
using System.Collections.Generic;
using System.Threading.Tasks;
class Program
{
static async Task Main(string[] args)
{
using (var 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"));
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
using (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);
var references = new List<MetadataReference>
{
MetadataReference.CreateFromFile(typeof(object).GetTypeInfo().Assembly.Location),
MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "Microsoft.AspNetCore.Mvc.dll")),
MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "System.Private.CoreLib.dll"))
};
var compilation = Microsoft.CodeAnalysis.CSharp.CSharpCompilation.Create("ApiClient")
.WithOptions(new Microsoft.CodeAnalysis.CSharp.CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary))
.AddReferences(references)
.AddSyntaxTrees(Microsoft.CodeAnalysis.CSharp.SyntaxFactory.ParseSyntaxTree(code));
var emitResult = compilation.Emit(memoryStream);
if (!emitResult.Success)
{
Console.WriteLine("Compilation errors:");
foreach (var diagnostic in emitResult.Diagnostics)
{
Console.WriteLine(diagnostic);
}
return null;
}
memoryStream.Seek(0, SeekOrigin.Begin);
return Assembly.Load(memoryStream.ToArray());
}
}
public interface IApiClient
{
// Replace with your actual method name and return type
Task<List<WeatherForecast>> GetWeatherForecastAsync();
}
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
Imports System.Net.Http
Imports System.IO
Imports System.Collections.Generic
Imports System.Threading.Tasks
Friend Class Program
Shared Async Function Main(ByVal args() As String) As Task
Using wclient = 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"))
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
Using 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 Using
End Using
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 = New List(Of MetadataReference) From {MetadataReference.CreateFromFile(GetType(Object).GetTypeInfo().Assembly.Location), MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "Microsoft.AspNetCore.Mvc.dll")), MetadataReference.CreateFromFile(Path.Combine(assemblyPath, "System.Private.CoreLib.dll"))}
Dim compilation = Microsoft.CodeAnalysis.CSharp.CSharpCompilation.Create("ApiClient").WithOptions(New Microsoft.CodeAnalysis.CSharp.CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary)).AddReferences(references).AddSyntaxTrees(Microsoft.CodeAnalysis.CSharp.SyntaxFactory.ParseSyntaxTree(code))
Dim emitResult = compilation.Emit(memoryStream)
If Not emitResult.Success Then
Console.WriteLine("Compilation errors:")
For Each diagnostic In emitResult.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
' Replace with your actual method name and return type
Function GetWeatherForecastAsync() As Task(Of List(Of WeatherForecast))
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 ClassDla API, którego chcemy używać, określamy adres URL specyfikacji Swagger (swaggerUrl). Następnie definiowany jest kod klienta wygenerowany i wykonany w postaci zestawu DLL. OpenApiDocument jest używany do asynchronicznego ładowania dokumentu Swaggera z podanego URL, używając FromJsonAsync. Aby zmienić wygenerowany kod klienta, dostosowujemy ustawienia generatora kodu (CSharpClientGeneratorSettings). W tym przykładzie podano nazwę klasy i przestrzeń nazw wygenerowanego kodu klienta.
Z załadowanego dokumentu Swagger konstrukujemy instancję CSharpClientGenerator i używamy jej do generowania kodu klienta. Utworzony kod klienta jest zapisywany w wyznaczonej ścieżce wyjściowej. Reagujemy na wszelkie wyjątki lub błędy, które mogą pojawić się podczas procedury, wyświetlając odpowiednie powiadomienia w konsoli.
NSwag może wykorzystywać specyfikację Swagger do generowania kodu klienckiego w wielu językach, w tym Java, TypeScript i C#. Dzięki temu programiści mogą w prosty sposób korzystać z interfejsów API w swoich aplikacjach.
Wykorzystując specyfikację Swagger jako podstawę, NSwag może również generować kod serwera, taki jak kontrolery ASP.NET Core. Pomaga to w szybkim tworzeniu kodu po stronie serwera do implementacji API.
Na podstawie specyfikacji Swagger, NSwag może generować interaktywną dokumentację API, taką jak Swagger UI. Niniejsza dokumentacja zapewnia łatwy w użyciu interfejs do przeglądania i testowania punktów końcowych API.
Aby zintegrować się z interfejsami API opartymi na SOAP, NSwag może generować klasy proxy. Umożliwia to programistom korzystanie z wygenerowanego kodu klienckiego w celu uzyskania dostępu do usług SOAP z poziomu ich aplikacji.
NSwag jest w stanie zweryfikować specyfikacje Swagger, aby upewnić się, że są one zgodne ze standardem OpenAPI/Swagger. Ułatwia to wykrycie wszelkich błędów lub rozbieżności w dokumentacji API.
Programiści mogą usprawnić proces tworzenia dokumentacji API, wykorzystując zalety obu technologii poprzez integrację NSwag z IronPDF. Programiści mogą tworzyć szczegółową dokumentację API sieci .NET, gotową do użycia w trybie offline, która jest łatwo dostępna i którą można udostępniać, używając NSwag do generowania specyfikacji Swagger oraz IronPDF do przekształcania ich w pliki PDF. Poniższe procedury stanowią część procesu integracji:
IronPDF wyróżnia się w konwersji HTML do PDF, zapewniając precyzyjne zachowanie oryginalnych układów i stylów. Idealnie nadaje się do tworzenia plików PDF z treści internetowych, takich jak raporty, faktury i dokumentacja. Dzięki obsłudze plików HTML, adresów URL i surowych ciągów znaków HTML, IronPDF z łatwością tworzy wysokiej jakości dokumenty PDF.
using IronPdf;
class Program
{
static void Main(string[] args)
{
var renderer = new ChromePdfRenderer();
// 1. Convert HTML String to PDF
var htmlContent = "<h1>Hello, IronPDF!</h1><p>This is a PDF from an HTML string.</p>";
var pdfFromHtmlString = renderer.RenderHtmlAsPdf(htmlContent);
pdfFromHtmlString.SaveAs("HTMLStringToPDF.pdf");
// 2. Convert HTML File to PDF
var htmlFilePath = "path_to_your_html_file.html"; // Specify the path to your HTML file
var pdfFromHtmlFile = renderer.RenderHtmlFileAsPdf(htmlFilePath);
pdfFromHtmlFile.SaveAs("HTMLFileToPDF.pdf");
// 3. Convert URL to PDF
var url = "http://ironpdf.com"; // Specify the URL
var pdfFromUrl = renderer.RenderUrlAsPdf(url);
pdfFromUrl.SaveAs("URLToPDF.pdf");
}
}Imports IronPdf
Friend Class Program
Shared Sub Main(ByVal args() As String)
Dim renderer = New ChromePdfRenderer()
' 1. Convert HTML String to PDF
Dim htmlContent = "<h1>Hello, IronPDF!</h1><p>This is a PDF from an HTML string.</p>"
Dim pdfFromHtmlString = renderer.RenderHtmlAsPdf(htmlContent)
pdfFromHtmlString.SaveAs("HTMLStringToPDF.pdf")
' 2. Convert HTML File to PDF
Dim htmlFilePath = "path_to_your_html_file.html" ' Specify the path to your HTML file
Dim pdfFromHtmlFile = renderer.RenderHtmlFileAsPdf(htmlFilePath)
pdfFromHtmlFile.SaveAs("HTMLFileToPDF.pdf")
' 3. Convert URL to PDF
Dim url = "http://ironpdf.com" ' Specify the URL
Dim pdfFromUrl = renderer.RenderUrlAsPdf(url)
pdfFromUrl.SaveAs("URLToPDF.pdf")
End Sub
End Class
Aby uzyskać dodatkowe informacje na temat funkcji, kompatybilności i dostępnych plików do pobrania IronPDF, odwiedź stronę IronPDF w serwisie NuGet.
Alternatywnie można włączyć IronPDF bezpośrednio do swojego projektu, korzystając z pliku DLL. Aby pobrać plik ZIP zawierający bibliotekę DLL, należy kliknąć link pobierania IronPDF. Rozpakuj plik i dodaj bibliotekę DLL do swojego projektu.
Używając NSwag, deweloperzy mogą szybciej tworzyć dokumentację API i kod klienta do użytku z API, stosując CodeGeneration.CSharp w połączeniu z IronPDF. Poniższe kroki stanowią część procesu integracji:
NSwag.CodeGeneration.CSharp. W tym kroku tworzenie klas klientów i metod komunikacji z punktami końcowymi API jest zautomatyzowane.CodeGeneration.CSharp. Na tym etapie formaty żądań/odpowiedzi, techniki uwierzytelniania oraz punkty końcowe klienta API są przekształcane w dokumentację zrozumiałą dla człowieka.using IronPdf;
using System.Text;
using System.Collections.Generic;
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 HtmlToPdf();
var pdf = renderer.RenderHtmlAsPdf(sb.ToString());
pdf.SaveAs("output.pdf");
Console.WriteLine("PDF generated successfully!");
Console.ReadKey();Imports IronPdf
Imports System.Text
Imports System.Collections.Generic
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 HtmlToPdf()
Dim pdf = renderer.RenderHtmlAsPdf(sb.ToString())
pdf.SaveAs("output.pdf")
Console.WriteLine("PDF generated successfully!")
Console.ReadKey()Powyższy kod uzyskuje dostęp do pobranych danych z obiektu wynikowego i dodaje pola Date, TemperatureF, TemperatureC, i Summary do akapitów w pętli. Następnie określa ścieżkę do pliku wyjściowego dla PDF, po czym powiadamia użytkownika, że PDF został pomyślnie wygenerowany.
Poniżej znajduje się wynik działania powyższego kodu.
CodeGeneration technologie NSwag jak CSharp i IronPDF współpracują ze sobą dobrze, aby usprawnić procesy produkcji kodu klienta i dokumentacji API. Programiści mogą przyspieszyć tworzenie rozwiązań opartych na API, zautomatyzować tworzenie dokumentacji API oraz generować profesjonalnie wyglądające publikacje w formacie PDF poprzez integrację tych narzędzi z aplikacjami napisanymi w języku C#. NSwag.CodeGeneration.CSharp z IronPDF oferuje deweloperom kompletne rozwiązanie do efektywnego dokumentowania API i produkcji kodu klienta w C#, niezależnie od tego, czy rozwijają aplikacje desktopowe, webowe, czy też oparte na chmurze.
Pakiet Lite obejmuje Licencję wieczystą, roczną konserwację oprogramowania oraz aktualizację biblioteki. IronPDF oferuje bezpłatną licencję z ograniczeniami dotyczącymi redystrybucji i czasu. Użytkownicy mogą ocenić rozwiązanie w okresie próbnym bez konieczności oglądania znaku wodnego. Aby uzyskac dodatkowe informacje na temat ceny i licencji, prosze zapoznac sie z informacjami licencyjnymi IronPDF. Przejdź do strony bibliotek Iron Software, aby uzyskać dodatkowe informacje na temat bibliotek produktów Iron Software.
Jacob Mellor jest Chief Technology Officer w Iron Software i wizjonerskim inżynierem, pionierem technologii C# PDF. Jako pierwotny deweloper głównej bazy kodowej Iron Software, kształtuje architekturę produktów firmy od jej początku, przekształcając ją wspólnie z CEO Cameron Rimington w firmę liczącą ponad 50 osób, obsługującą NASA, Teslę i światowe agencje rządowe.
IronPDF jest częścią IRONSUITE
10 produktów API .NET dla twoich dokumentów biurowych
Kiedy potrzebujesz, aby twój PDF wyglądał jak HTML, szybko.
