跳至頁尾內容
  1. IronPDF
  2. IronPDF博客
  3. .NET 幫助
  4. Nswag C#
.NET 幫助

Nswag C#（開發者使用方法）

Jacob Mellor，Team Iron 首席技術官
雅各·梅勒
更新:

API 在現今的軟體開發環境中是不可或缺的，因為它們有助於各種軟體系統和元件之間的溝通。 為了讓開發人員有效率地使用 API，必須有詳盡且易懂的說明文件。 NSwag C# 和 IronPDF 是兩種可以幫助 C# API 文件工作流程的有效工具。 本文章將討論如何使用 NSwag 以 .NET Core 產生 API 規格，並使用 IronPDF 從這些規格產生高品質的 PDF 文件。

如何在 C# 中使用 NSwag;。

1.使用 Swagger UI 建立 RESTful Web API。 2.建立 C# 主控台應用程式。 3.安裝 NSwag 函式庫。 4.匯入命名空間並建立物件。 5.將 Swagger JSON 處理為 C# 程式碼。 6.執行程式碼並顯示結果。

瞭解 NSwag

為了讓使用 ASP.NET Web API、ASP.NET Core 或其他 .NET Framework 建構的 API 更容易建立 Swagger 規格或 OpenAPI 文件，我們建立了一個名為 NSwag 的 .NET Swagger 工具鏈。

NSwag 的特點

製作 Swagger 規格

控制器、模型和 .NET 集合都可由 NSwag 用來自動產生 Swagger 規格。 NSwag 可透過檢視 API 程式碼的結構，產生涵蓋 API 端點、請求/回應形式、驗證技術等的綜合文件。

連接至 .NET 專案。

透過將 NSwag 與 .NET 專案整合，開發人員可以輕鬆地將 Swagger 的產生納入他們的開發流程。 開發人員可透過在 .NET Core 專案中加入 NSwag 來確保文件會隨著程式碼庫更新，而 NSwag 會在每次建立專案時自動產生 Swagger 規格。

個人化與擴充

透過 NSwag 提供的廣泛客製化可能性，開發人員可以輕鬆調整所產生的 Swagger 規格，以符合他們獨特的需求。 開發人員可透過組態設定和注解控制所產生文件的許多元件，包括回應碼、參數解釋和路由命名慣例。

開始使用 NSwag

在 C# Console App 中設定 NSwag

NSwag 基礎類庫包括核心、註解和代碼生成命名空間，應可從 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 集合的用戶端程式碼。 OpenApiDocument 使用 FromJsonAsync 從給定的 URL 異步載入 Swagger 文件。 為了改變所產生的用戶端程式碼，我們調整程式碼產生器的設定 (CSharpClientGeneratorSettings)。 在本範例中，指定了所產生的用戶端程式碼的類別名稱和命名空間。

從載入的 Swagger 文件，我們建構 CSharpClientGenerator 的實例，並使用它來產生用戶端程式碼。 建立的用戶端程式碼會儲存到指定的輸出路徑。 我們會回應程序中可能出現的任何異常或錯誤，在主控台上顯示相關通知。

NSwag C# (How It Works For Developers)：圖 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 for .NET 將其轉換為 PDFs 來製作詳盡、可離線使用的 .NET Web API 文件，且這些文件可隨時使用和分享。 以下程序是整合流程的一部分：

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");
    }
}
$vbLabelText   $csharpLabel

安裝 IronPDF。

  • 啟動 Visual Studio 專案。
  • 選擇"工具">"NuGet Package Manager">"Package Manager Console"。
  • 開啟您的指令提示，並在套件管理員控制台中輸入下列指令：
Install-Package IronPdf
  • 另外，您也可以使用 NuGet Package Manager for Solutions 安裝 IronPDF。
  • 探索並從搜尋結果中選擇 IronPDF 套件，然後按一下"安裝"選項。 Visual Studio 將代您處理下載與安裝。

!NSwag C# (How It Works For Developers)：圖 3 - 使用管理 NuGet Package for Solution 安裝 IronPDF，方法是在 NuGet Package Manager 的搜尋列中搜尋 "IronPdf"，然後選擇專案並點選安裝按鈕。

  • NuGet 將安裝 IronPDF 套件以及專案所需的任何相依性。
  • 安裝完成後，IronPdf 即可用於您的專案。

透過 NuGet 網站安裝

有關 IronPDF 功能、相容性和可用下載的其他資訊，請造訪 NuGet 上的 IronPDF 頁面。

利用 DLL 安裝

另外，您也可以使用 IronPDF 的 DLL 檔案，直接將 IronPDF 納入您的專案中。若要下載包含 DLL 的 ZIP 檔案，請點選 IronPDF 下載連結。 解壓縮檔案並將 DLL 加入您的專案。

實作邏輯

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

1.產生用戶端程式碼：若要從 Swagger 規格建立 C# 用戶端程式碼，請使用 NSwag.CodeGeneration.CSharp. 與 API 端點通訊的用戶端類別和方法的建立在此步驟中自動完成。 2.利用 NSwag 取得資料：若要從 Swagger 規格產生 JSON 文件，請使用 CodeGeneration.CSharp. 在此階段中，請求/回應格式、驗證技術和 API 用戶端點都會建立為人類可讀的文件。 3.將 JSON 轉換為 PDF：若要將產生的程式碼結果轉換為 PDF 文件，請使用 IronPDF。 在此階段，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, TemperatureC, 和 Summary 附加到迴圈中的段落。然後指定 PDF 的輸出檔案路徑，再通知使用者 PDF 已成功產生。

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

NSwag C# (How It Works For Developers)：圖 4 - 上述程式碼的輸出範例

結論

CodeGeneration NSwag 技術，如 CSharp 和 IronPDF 可以很好地配合，以簡化客戶端程式碼製作和 API 文件流程。 開發人員可藉由將這些工具整合至 C# 應用程式，加速建立 API 驅動的解決方案、自動化建立 API 文件，以及製作專業樣貌的 PDF 出版物。 NSwag.CodeGeneration.CSharp 搭配 IronPDF 可為開發人員提供完整的解決方案，無論是開發桌上型電腦、Web 或雲端應用程式，都能有效率地以 C# 記錄 API 並產生用戶端程式碼。

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 增強了 API 文件工作流程，讓開發人員可以將基於 HTML 的 API 文檔轉換為專業的、可共享的 PDF 文檔，使資訊可以離線存取。

在 Visual Studio 專案中使用 IronPDF 需要哪些步驟？

要在 Visual Studio 專案中使用 IronPDF，可以透過 NuGet 套件管理器搜尋 IronPDF 並點擊「安裝」來安裝它，或使用套件管理器控制台和命令Install-Package IronPdf 。

如何使用 NSwag 產生互動式 API 文件？

NSwag 可以透過產生 Swagger UI 來產生互動式 API 文檔，從而提供一個用戶友好的介面，可以直接在瀏覽器中探索和測試 API 端點。

使用 NSwag 編寫 API 文件有哪些好處？

NSwag 可自動產生 API 文檔，確保其始終與程式碼庫保持同步。它還支援創建互動式文件和客戶端程式碼，從而簡化開發流程。

IronPDF 如何處理 HTML 內容以建立 PDF 檔案？

IronPDF 使用其渲染引擎將 HTML 內容（包括 CSS 和 JavaScript）轉換為 PDF 格式，使其成為從基於 Web 的內容建立精確、可離線使用的文件的理想選擇。

Jacob Mellor，Team Iron 首席技術官
雅各·梅勒
  現在就和工程團隊聊天吧
首席技術長

Jacob Mellor 是 Iron Software 的首席技術官，也是一位富有遠見的工程師，率先開發了 C# PDF 技術。作為 Iron Software 核心程式碼庫的最初開發者，他自公司成立之初便參與塑造了其產品架構，並與執行長 Cameron Rimington 一起將其發展成為一家擁有 50 多名員工、服務於 NASA、特斯拉和全球政府機構的公司。

Jacob 於 1998 年至 2001 年在曼徹斯特大學獲得土木工程一級榮譽學士學位。 1999 年，他在倫敦創辦了自己的第一家軟體公司；2005 年，他創建了自己的第一個 .NET 元件。此後，他專注於解決微軟生態系統中的複雜問題。

他的旗艦產品 IronPDF 和 IronSuite .NET 庫在全球 NuGet 上的安裝量已超過 3000 萬次，其基礎程式碼持續為全球開發者工具提供支援。憑藉 25 年的商業經驗和 41 年的程式設計專長，Jacob 始終致力於推動企業級 C#、Java 和 Python PDF 技術的創新，同時指導下一代技術領導者。

相關文章

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