.NET 幫助

Nswag C# (開發人員如何使用)

坎納帕特·烏頓潘

2024年6月6日

介紹

在當今的軟體開發環境中，API 是必不可少的，因為它們促進了各種軟體系統和組件之間的通信。為了讓開發人員高效使用 API，必須提供詳盡且易懂的文件。兩個可以幫助 C# API 文件工作流程的有效工具是 NSwag C# 和 IronPDF。這篇文章將討論如何使用 NSwag 來生成API 規範使用 .NET Core 並使用 IronPDF 根據這些規範生成高質量的 PDF 文件。

如何在 C# 中使用 NSwag

使用 Swagger UI 創建休息式網頁 API。
創建一個 C# 控制台應用程式。
安裝 NSwag 庫。
導入命名空間並創建對象。
將 Swagger JSON 轉換為 C# 代碼。
執行代碼並顯示結果。

了解 NSwag

一個名為 NSwag 的 .NET Swagger 工具鏈是為了簡化為使用 ASP.NET Web API、ASP.NET Core 或其他 .NET 框架構建的 API 創建 Swagger 規範或 OpenAPI 文件而設計的。

NSwag 的特性

Swagger 規範的製作

控制器、模型和 .NET 程式集都可以被 NSwag 用來自動生成 Swagger 規範。 NSwag 通過檢查 API 代碼的結構生成涵蓋 API 端點、請求/響應格式、身份驗證技術等方面的綜合文檔。

連接到 .NET 項目

開發人員可以透過將 NSwag 與 .NET 專案整合，輕鬆地將 Swagger 生成納入他們的開發流程中。開發人員可以通過將 NSwag 添加到 .NET Core 專案中來確保文件與代碼庫同步更新，這將在每次建置專案時自動生成 Swagger 規範。

個性化和擴展

有了NSwag提供的多種自訂選項，開發人員可以輕鬆調整生成的Swagger規範，以滿足其獨特需求。開發人員可以透過配置設置和註解，控制生成的文件的許多組件，包括響應代碼、參數說明和路由命名約定。

入門 NSwag

在 C# 控制台應用程式中設置 NSwag

NSwag 基礎類別庫包括核心、註解和代碼生成命名空間，可以通過從 NuGet 安裝來獲得。將 NSwag 整合到 C# 應用程式中以生成代碼和 Swagger 規範，以及 NSwag 如何提高開發過程的效率。

NSwag C#（開發人員如何使用）：圖 1 - 在 Visual Studio 套件管理員中瀏覽並安裝 NSwag

在 Windows 控制台和表單中實施 NSwag

透過自動化的客戶端生成，開發人員可以通過將NSwag整合到Windows桌面應用程式中，從而高效地生成用於從桌面應用程式中直接訪問API的程式碼。在開發與線上服務或 RESTful API 通信的桌面應用程式時，這可能非常有幫助。

NSwag 可用於網路應用程式中，以生成內部 API 的 API 文件和用於調用外部 API 的用戶端代碼。這有助於開發人員保持應用程式的前端和後端組件一致。

NSwag C# 示例

以下是展示如何使用 NSwag 生成 C# 客戶端代碼的示例代碼：

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

對於我們希望使用的 API，我們指定 Swagger 規範的 URL(swaggerUrl). 然後定義生成並執行到 DLL 程式集的用戶端代碼。 OpenApiDocument 被使用。要從給定的 URL 異步載入 Swagger 文件，請使用 FromJsonAsync。要更改生成的客戶端代碼，我們需調整代碼生成器的設置。(CSharpClientGeneratorSettings). 在此範例中，生成的客戶端程式碼的類名和命名空間已被指定。

從加載的 Swagger 文檔中，我們構建一個 CSharpClientGenerator 實例，並使用它生成客戶端代碼。(客戶代碼). 生成的客戶端代碼保存到指定的輸出路徑。我們會回應程序中可能出現的任何異常或錯誤，並在控制台上顯示相關通知。

NSwag C#（它如何為開發人員工作）：圖 2 - 來自上述代碼的控制台輸出

NSwag 操作

生成客戶端代碼

NSwag 可以使用 Swagger 規範來生成多種語言的客戶端代碼，包括 Java、TypeScript 和 C#。這使開發者可以輕鬆地在他們的應用程式中使用 API。

生成伺服器代碼

使用 Swagger 規範作為基礎，NSwag 也可以生成伺服器代碼，例如 ASP.NET Core 控制器。這有助於快速構建 API 實作的伺服器端代碼。

製作互動式 API 文件

給定一個 Swagger 規範，NSwag 可以生成交互式 API 文檔，例如 Swagger UI。本文件提供了一個易於使用的介面，用於探索和測試 API 端點。

生成代理類別

要與基於 SOAP 的 API 集成，NSwag 可以生成代理類。這使程式設計師能夠使用生成的客戶端代碼從應用程式內部訪問SOAP服務。

驗證 Swagger 規範

NSwag 能夠驗證 Swagger 規範，以確保它們遵循 OpenAPI/Swagger 標準。這樣可以更容易查看 API 文件中的任何錯誤或差異。

將 NSwag 與 IronPDF 整合

開發人員可以通過結合使用 NSwag 和 IronPDF，利用這兩種技術的優勢來改進 API 文檔的工作流程。開發人員可以使用 NSwag 生成 Swagger 規範來製作詳細的可離線使用的 .NET 網頁 API 文件，這些文件易於存取和共享，並且IronPDF 將其轉換為 PDF. 以下程序是整合過程的一部分：

IronPDF 擅長於HTML轉PDF轉換，確保準確保留原始佈局和樣式。它非常適合從基於網絡的內容（如報告、發票和文檔）創建PDF。 IronPDF 支援 HTML 檔案、URL 和原始 HTML 字串，輕鬆製作高品質的 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");
    }
}

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

安裝 IronPDF

啟動 Visual Studio 專案。
選擇「工具」>「NuGet 套件管理器」>「套件管理員主控台」。
開啟命令提示字元，並在套件管理器主控台中輸入以下命令：

Install-Package IronPdf

或者，您可以使用 NuGet 套件管理器為方案安裝 IronPDF。
瀏覽並從搜索結果中選擇 IronPDF 套件，然後點擊「安裝」選項。 Visual Studio 會代表您處理下載和安裝。
NuGet 將安裝 IronPDF 套件和您專案所需的任何相依性。
安裝後，IronPDF 可以用於您的項目。

通過NuGet網站安裝

如需有關 IronPDF 功能、相容性和可供下載的更多資訊，請造訪IronPDF 在 NuGet 上的頁面.

利用 DLL 進行安裝

或者，您可以透過使用 IronPDF 的 DLL 檔直接將其整合到您的專案中。要下載包含 DLL 的 ZIP 檔，請點選IronPDF 下載連結. 解壓縮該文件並將 DLL 添加到您的項目中。

要獲取包含DLL的ZIP檔案，解壓縮後，將DLL整合到您的專案中。

實現邏輯

透過使用 NSwag，開發人員可以利用 CodeGeneration.CSharp 與 IronPDF 結合，更快速地創建 API 文件和用於使用 API 的客戶端代碼。以下步驟是整合工作流程的一部分：

生成客戶端代碼： 要從 Swagger 規範創建 C# 客戶端代碼，請使用 NSwag.CodeGeneration.CSharp。在此步驟中，自動化創建用於與 API 端點通信的客戶端類和方法。
利用 NSwag 獲取資料： 要從 Swagger 規格生成 JSON 文件，請使用 CodeGeneration.CSharp。在此階段，請求/回應格式、身份驗證技術和 API 客戶端端點被創建為人類可讀的文檔。
將 JSON 轉換為 PDF： 要將生成的代碼結果轉換為 PDF 文檔，請使用 IronPDF。在此階段，HTML 文本會被轉換為精美的 PDF 文件，準備好用於分享和分發。
改進 PDF 文檔： 使用 IronPDF 向 PDF 文檔添加更多內容，例如標題、頁腳、水印或獨特的品牌標識。此階段賦予開發者個人化 PDF 文件外觀和品牌的能力，以符合他們的喜好。

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()

上述程式碼從結果對象中存取檢索到的數據，並在迴圈中將 Date、TemperatureF、TemperatureC 和 Summary 欄位附加到段落中。然後指定 PDF 的輸出文件路徑，並通知使用者 PDF 已成功生成。

以下是上述程式碼的結果。

NSwag C#（對開發人員的運作方式）：圖 4 - 上述代碼的示例輸出

結論

CodeGeneration NSwag 技術如 CSharp 和 IronPDF 能夠很好地協同工作，以簡化客戶端代碼生成和 API 文檔流程。開發人員可以透過將這些工具整合到 C# 應用程式中，加速 API 驅動解決方案的創建、自動化 API 文件的創建，並生成專業外觀的 PDF 出版物。使用 IronPDF 的 NSwag.CodeGeneration.CSharp 為開發者提供了一個完整的解決方案，能有效地記錄 API 並生成 C# 的客戶端代碼，無論是開發桌面、網頁還是基於雲的應用程式。

$749 Lite 套件包含永久授權、一年軟體維護以及庫的升級。 IronPDF 提供免費授權，但對重新分發和時間有限制。用戶可以在試用期內評估該解決方案，而不必看到浮水印。如需有關價格和許可證的更多資訊，請參閱IronPDF 的授權資訊. 前往Iron Software 函式庫頁面有關 Iron Software 產品庫的更多信息。

坎納帕特·烏頓潘

立即與工程團隊聊天

軟體工程師

在成為軟體工程師之前，Kannapat 在日本北海道大學完成了環境資源博士學位。在攻讀學位期間，Kannapat 也成為了車輛機器人實驗室的成員，該實驗室隸屬於生物生產工程學系。2022 年，他利用自己的 C# 技能，加入了 Iron Software 的工程團隊，專注於 IronPDF 的開發。Kannapat 珍視這份工作，因為他可以直接向負責撰寫大部分 IronPDF 程式碼的開發人員學習。除了同儕學習外，Kannapat 還享受在 Iron Software 工作的社交方面。當他不在撰寫程式碼或文件時，Kannapat 通常會在 PS5 上玩遊戲或重看《最後生還者》。

< 上一頁
Dapper C#（對開發者的工作原理）

下一個 >
流暢的 C#（它對開發者的運作原理）