.NET 幫助

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

發佈 2024年6月6日

介紹

API在當今的軟體開發環境中至關重要，因為它們促進了各種軟體系統和組件之間的通信。為了讓開發人員有效地使用API，必須有詳細且易於理解的文檔。兩個可以幫助C# API文檔工作流的有效工具是NSwag c#和IronPDF。本篇文章將討論如何使用NSwag來生成 API 使用 IronPDF 與 .NET Core 來從這些規格中生成高品質的 PDF 文件。

如何在C#中使用NSwag

使用Swagger UI創建一個RESTful Web 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可以用在Web應用程式中，以生成內部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

VB C#

對於我們希望使用的 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 規範並使用 IronPDF 將其轉換為 PDF，生成詳細的、可離線使用的 net web API 文檔，這些文檔可以輕鬆獲取和分享。文檔以下程序是整合過程的一部分：

安裝 IronPDF

開始 Visual Studio 專案。
選擇 "工具" > "NuGet 套件管理員" > "套件管理員控制台"。
打開命令提示符，並在套件管理員控制台中輸入以下命令：

Install-Package IronPdf

另外，您可以使用 NuGet 套件管理器來安裝 IronPDF。
您可以從搜索結果中探索並選擇 IronPDF 套件，然後點擊“安裝”選項。Visual Studio 將會代您處理下載和安裝。
NuGet 將安裝 IronPDF 套件以及您專案所需的任何相依項目。
安裝後，IronPDF 可以用於您的專案。

通过 NuGet 网站安装

有关 IronPDF 的功能、兼容性和可下载内容的更多信息，请访问 NuGet 网站上的页面 https://www.nuget.org/packages/IronPdf。

使用DLL安裝

或者，您可以通過使用DLL文件直接將IronPDF納入您的專案中。要下載包含DLL的ZIP文件，請點擊這個链接連結解壓縮文件並將 DLL 添加到您的項目中。

獲取包含 DLL 的 ZIP 文件。解壓縮後，將 DLL 合併到您的項目中。

實現邏輯

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

生成用戶端代碼： 使用NSwag.CodeGeneration.CSharp從 Swagger 規範生成 C# 用戶端代碼。此步驟自動化了與 API 端點通信的用戶端類和方法的創建。
使用 NSwag 獲取數據： 使用CodeGeneration.CSharp從 Swagger 規範生成 JSON 文件。在此階段，請求/響應格式、認證技術和 API 客戶端端點被創建成人類可讀的文件。
將 JSON 轉換為 PDF： 使用 IronPDF 將生成的代碼結果轉換為 PDF 文件。在此階段，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()

VB C#

上面的代碼從結果對象中訪問檢索到的數據，並在循環中將 Date、TemperatureF、TemperatureC 和 Summary 字段附加到段落中。然後指定 PDF 的輸出文件路徑，並通知用戶已成功生成 PDF。

以下是上述代碼的結果。

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

結論

CodeGeneration NSwag 技術如 CSharp 和 IronPDF 良好地協同合作，以簡化客戶端代碼生產和 API 文檔流程。開發人員可以通過將這些工具集成到 C# 應用程式中，加快 API 驅動解決方案的創建，自動生成 API 文檔，並製作專業的 PDF 刊物。 NSwag.CodeGeneration.CSharp 與 IronPDF 一起提供了一個完整的解決方案，讓開發人員不論開發桌面，網頁，或雲端應用程式，都能有效地記錄 API 並生成 C# 客戶端代碼。

$749 Lite 套餐包括永久授權，一年的軟體維護和對庫的升級。IronPDF 提供具有限制的免費授權，限制包括再分發和使用時間。使用者可以在試用期間評估該解決方案而不必看到浮水印。有關價格和授權的更多信息，請參閱 IronPDF 的授權頁面。頁面請前往此頁面獲取有關 Iron Software 的更多資訊函式庫.

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

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