.NET 帮助

Nswag C#（它如何为开发人员工作）

雷根·彭

2024年六月6日

介绍

在当今的软件开发环境中，API 是必不可少的，因为它们促进了各种软件系统和组件之间的通信。为了让开发人员高效地使用 API，必须有详尽易懂的文档。 NSwag C# 和 IronPDF 是两个可以帮助 C# API 文档工作流程的有效工具。本文章将讨论如何使用 NSwag 生成应用程序接口规范您可以使用 IronPDF for .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 Framework 构建的 API 创建 Swagger 规范或 OpenAPI 文档。

NSwag 的功能

制作 Swagger 规范

NSwag 可以使用控制器、模型和 .NET 程序集来自动生成 Swagger 规范。 NSwag 通过检查 API 代码的结构，生成涵盖 API 端点、请求/响应形式、验证技术等内容的综合文档。

与 .NET 项目的连接

通过将 NSwag 与 .NET 项目集成，开发人员可以轻松地将 Swagger 生成纳入其开发流程。开发人员可以通过在 .NET Core 项目中添加 NSwag 来确保文档与代码库同步更新，NSwag 会在每次构建项目时自动生成 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。要更改生成的客户端代码，我们需要调整代码生成器的设置(CharpClientGeneratorSettings). 在本例中，指定了生成的客户端代码的类名和命名空间。

从加载的 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 Web API 文档，从而制作出详尽的、离线就绪的 .NET Web 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 Package Manager for Solutions 安装 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()

上面的代码访问从结果对象中获取的数据，并在一个循环中将日期、温度F、温度C和摘要字段添加到段落中。然后指定 PDF 的输出文件路径，然后通知用户已成功生成 PDF。

以下是上述代码的结果。

NSwag C#（如何为开发人员工作）：图 4 - 上述代码的输出示例

结论

CodeGeneration NSwag 技术（如 CSharp 和 IronPDF）可以很好地配合使用，以简化客户端代码生产和 API 文档编制流程。通过将这些工具集成到 C# 应用程序中，开发人员可以加快 API 驱动型解决方案的创建速度，自动创建 API 文档，并制作出外观专业的 PDF 出版物。带有 IronPdf 的 NSwag.CodeGeneration.CSharp 为开发人员提供了一个完整的解决方案，无论他们是开发桌面、Web 还是基于云的应用程序，都可以高效地用 C# 编写 API 文档并生成客户端代码。

$749 Lite 捆绑软件包括一个永久许可证、一年的软件维护和一个升级库。 IronPdf 提供免费授权，但对再分发和时间有限制。用户可以在试用期间对解决方案进行评估，而无需查看水印。有关价格和许可证的更多信息，请参见IronPDF 的许可信息. 前往Iron Software 库页面如需了解有关 Iron Software 产品库的更多信息，请联系我们。

雷根·彭

立即与工程团队聊天

软件工程师

Regan毕业于雷丁大学，拥有电子工程学士学位。在加入Iron Software之前，他的前工作职位要求他专注于单一任务；他在Iron Software最喜欢的是能进行多种工作，无论是增加销售价值、技术支持、产品开发还是营销。他喜欢了解开发人员如何使用Iron Software的库，并利用这些知识不断改进文档和开发产品。

< 前一页
Dapper C#（它如何为开发人员工作）

下一步 >
Flunt C#（如何为开发者工作）