訊息圖示
跳過到頁腳內容
  1. IronPDF
  2. IronPDF博客
  3. .NET幫助
  4. Nswag C#
.NET幫助

Nswag C#（對於開發者的運行原理）

Jacob Mellor, Team Iron 首席技術官
Jacob Mellor
更新:

API在當今軟體開發環境中至關重要，因為它們促進了各種軟體系統和組件之間的通信。 為了讓開發者能夠有效地使用API，必須提供全面且易懂的文件。 兩個可以幫助C# API文件工作流程的有效工具是NSwag C#和IronPDF。 本文將討論如何使用NSwag生成API規範，然後使用IronPDF以.NET Core生產這些規範的高質量PDF文件。

How to Use NSwag in C#

  1. 使用Swagger UI創建一個RESTful web API。
  2. 創建一個C#控制台應用程式。
  3. 安裝NSwag程式庫。
  4. 導入命名空間並創建物件。
  5. 將Swagger JSON轉換為C#代碼。
  6. 執行代碼並顯示結果。

了解NSwag

一個叫做NSwag的.NET Swagger工具鏈旨在幫助為使用ASP.NET Web API、ASP.NET Core或其他.NET框架構建的API創建Swagger規範或OpenAPI文檔。

NSwag的功能

生成Swagger規範

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

連接到.NET專案

開發者可以通過將NSwag與.NET專案整合，輕鬆將Swagger生成納入他們的開發過程。 開發者可以通過將NSwag添加到.NET Core專案中來確保文檔與代碼庫保持一致，並在每次項目構建時自動生成Swagger規範。

個性化和擴展

NSwag提供了廣泛的自定義選項，開發者可以輕鬆調整生成的Swagger規範以滿足各自的需求。 開發者可以通過配置設置和批註控制生成文件的許多組件，包括響應代碼、參數說明和路由命名約定。

開始使用NSwag

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

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

NSwag C# (How It Works For Developers): 圖1 - 在Visual Studio套件管理器中搜索並安裝NSwag

在Windows Console和Forms中實施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;
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; }
    }
}
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; }
    }
}
$vbLabelText   $csharpLabel

對於要使用的API，我們指定Swagger規範的URL(swaggerUrl)。 然後生成客戶端代碼並執行到DLL程序集中進行定義。 FromJsonAsync。 為了修改生成的客戶端代碼，我們調整代碼生成器的設置(CSharpClientGeneratorSettings)。 在這個示例中，指定了生成的客戶端代碼的類名和命名空間。

從加載的Swagger文檔中，我們構建CSharpClientGenerator的實例並用其生成客戶端代碼。 創建的客戶端代碼被保存到指定的輸出路徑。 我們回應在過程中可能出現的任何例外或錯誤，並在控制台上顯示相關通知。

NSwag C# (How It Works For Developers): 圖2 - 上述代碼的控制台輸出

NSwag操作

生成客戶端代碼

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

生成服務器代碼

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

製作交互式API文檔

給定一個Swagger規範，NSwag可以製作交互式API文檔，例如Swagger UI。 這份文檔提供了易于使用的界面，用於瀏覽和測試API端點。

生成代理類

為了與SOAP基於SOAP的API進行整合，NSwag可以生成代理類。 這使得程式設計師能夠使用生成的客戶端代碼從應用中訪問SOAP服務。

驗證Swagger規範

NSwag能驗證Swagger規範，以確保它們符合OpenAPI/Swagger標準。 這使得更容易看到API文檔中的任何錯誤或不符之處。

將NSwag與IronPDF整合

開發者可以通過將NSwag與IronPDF整合，利用這兩項技術的優勢來改進API文檔工作流程。 開發者可以通過NSwag生成Swagger規範，IronPDF將其轉換為PDF，製作詳細的、離線就緒的.NET網頁API文件，方便分享和使用。 整合過程包括以下步驟：

IronPDF在HTML到PDF轉換中表現出色，確保精確保留原有版面和樣式。 它非常適合從基於網頁的內容如報告、發票和文件中創建PDF。 支持HTML文件、URL和原始HTML字串，IronPDF可輕鬆生成高品質的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");
    }
}
$vbLabelText   $csharpLabel

安裝 IronPDF

  • 開始 Visual Studio 專案。
  • 選擇 "工具" > "NuGet 程式包管理員" > "程式包管理員控制台"。
  • 打開命令提示，並在套件管理器控制台中輸入以下命令：
Install-Package IronPdf
  • 或者，您可以使用 NuGet 程式包管理器安裝 IronPDF。
  • 探索並從搜索結果中選擇IronPDF包，然後點擊"安裝"。 Visual Studio 將代表您處理下載和安裝。

NSwag C# (How It Works For Developers): Figure 3 - Install IronPDF using the Manage NuGet Package for Solution by searching IronPdf in the search bar of NuGet Package Manager, then select the project and click on the Install button.

  • NuGet將安裝IronPDF包和專案所需的任何依賴項。
  • 安裝後，IronPDF可用於您的專案。

透過 NuGet 網站安裝

如需有關IronPDF的功能、兼容性和可用下載的更多信息，請訪問IronPDF頁面在NuGet上。

利用 DLL 進行安裝

或者，您可以直接將IronPDF整合到專案中使用DLL文件。要下載包含DLL的ZIP文件，請單擊IronPDF下載鏈接。 解壓縮文件並將 DLL 添加到您的專案中。

實現邏輯

通過利用NSwag，開發者可以使用CodeGeneration.CSharp與IronPDF結合，快速創建API文檔和客戶端代碼。 整合工作流程包括以下步驟：

  1. 生成客戶端代碼： 使用NSwag.CodeGeneration.CSharp從Swagger規範創建C#客戶端代碼。 創建與API端點通信的客戶端類別和方法的過程在此步驟中自動化。
  2. 利用NSwag獲取數據： 使用CodeGeneration.CSharp從Swagger規範生成JSON文檔。 在此階段，請求/響應格式、身份驗證技術和API客戶端端點被創建為人類可讀文檔。
  3. 將JSON轉換為PDF： 使用IronPDF將生成的代碼結果轉換為PDF文檔。 在此階段，將HTML文本轉換為已準備好共享和分發的優雅PDF文件。
  4. 改進PDF文檔： 使用IronPDF在PDF文檔中添加更多內容，例如標題、頁腳、水印或獨特品牌。 此階段使開發者能夠根據個人喜好自定義PDF文檔的外觀和品牌。
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();
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();
$vbLabelText   $csharpLabel

上述代碼從結果物件中訪問檢索到的數據，並將字段Date, TemperatureF, Summary添加到循環中的段落。接著，它指定PDF的輸出文件路徑，然後通知用戶PDF已成功生成。

以下是上述代碼的結果。

NSwag C# (How It Works For Developers): 圖4 - 上述代碼的示例輸出

結論

CodeGeneration NSwag技術，如CSharp和IronPDF一起運行良好，以簡化客戶端代碼生產和API文件過程。 開發者可以通過將這些工具整合到C#應用程序中，加速API驅動解決方案的創建，自動化API文件的生成，並生成專業外觀的PDF出版物。 NSwag.CodeGeneration.CSharp與IronPDF一起為開發者提供了一種完整的解決方案，無論是開發桌面、網路或基於雲的應用，皆能有效地記錄API並生產C#客戶端代碼。

Lite捆綁包包括一個永久授權、一年的軟體維護和程式庫升級。 IronPDF 提供的免費授權有限制再分發和時間。用戶可以在試用期期間評估該解決方案，而無需看到浮水印。 有關價格和授權的更多信息，請參閱IronPDF的授權信息。 如需Iron Software產品程式庫的更多信息，請訪問Iron Software程式庫頁面。

常見問題解答

NSwag 如何幫助生成 C# 的 API 規範？

NSwag 能夠自動從 .NET Core 項目中生成 API 規範，稱為 Swagger 或 OpenAPI 文檔。這確保了 API 文檔始終與代碼庫保持同步。

將 Swagger 規範轉換為 PDF 文檔的過程是什麼？

要將 Swagger 規範轉換為 PDF 文檔，可以使用 IronPDF。首先，使用 NSwag 生成 Swagger 規範，然後利用 IronPDF 將這些規範的 HTML 內容轉換為高質量的 PDF。

如何將 NSwag 集成到 .NET 項目中？

將 NSwag 集成到 .NET 項目中，包括通過 NuGet 安裝 NSwag 庫，配置它以便在構建過程中生成 Swagger 規範，並使用生成的規範進行文檔和代碼生成。

NSwag 可以從一個 Swagger 規範生成客戶端和服務器端代碼嗎？

是的，NSwag 能夠從單個 Swagger 規範中生成 C#、Java 和 TypeScript 等語言的客戶端代碼，以及服務器端代碼如 ASP.NET Core 控制器。

IronPDF 如何增強 API 文檔工作流程？

IronPDF 通過允許開發人員將基於 HTML 的 API 文檔轉換為專業的、可共享的 PDF 文檔，增強了 API 文檔工作流程，從而使信息可以離線訪問。

在 Visual Studio 項目中使用 IronPDF 需要哪些步驟？

要在 Visual Studio 項目中使用 IronPDF，可以通過搜索 IronPDF 並單擊“安裝”以使用 NuGet 包管理器安裝它，或使用包管理器控制台的命令Install-Package IronPDF。

如何使用 NSwag 生成交互式 API 文檔？

NSwag 可以通過生成 Swagger UI 來生成交互式 API 文檔，這為在瀏覽器中直接探索和測試 API 端點提供了一個用戶友好的界面。

使用 NSwag 進行 API 文檔的好處有哪些？

NSwag 自動化 API 文檔生成，確保其始終與代碼庫保持最新。它還支持創建交互式文檔和客戶端代碼，簡化開發過程。

IronPDF 如何處理 HTML 內容以創建 PDF？

IronPDF 使用其渲染引擎將 HTML 內容（包括 CSS 和 JavaScript）轉換為 PDF 格式，是從基於網頁的內容創建精確且可離線準備的文檔的理想選擇。

Jacob Mellor, Team Iron 首席技術官
Jacob Mellor
  立即與工程團隊聊天
首席技術官

Jacob Mellor是Iron Software的首席技術官，也是開創C# PDF技術的前瞻性工程師。作為Iron Software核心代碼庫的原始開發者，他自公司成立以來就塑造了公司的產品架構，並與CEO Cameron Rimington將公司轉型為服務NASA、Tesla以及全球政府機構的50多人公司。

Jacob擁有曼徹斯特大學土木工程一級榮譽學士學位（1998年–2001年）。他於1999年在倫敦開立首家軟體公司，並於2005年建立了他的第一個.NET組件，專注於解決Microsoft生態系統中的複雜問題。

他的旗艦作品IronPDF和Iron Suite .NET程式庫全球已獲得超過3000萬次NuGet安裝，他的基礎代碼不斷在全球各地驅動開發者工具。擁有25年以上的商業經驗和41年的編碼專業知識，Jacob仍然專注於推動企業級C#、Java和Python PDF技術的創新，同時指導下一代技術領導者。

相關文章

30 天試用→完整產品。無限制。無需信用卡。 開始免費試用

Iron Support Team

We're online 24 hours, 5 days a week.
Chat
Email
Call Me