.NET 帮助

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

发布 2024年六月6日

简介

在当今的软件开发环境中，应用程序接口（API）是必不可少的，因为它们有助于各种软件系统和组件之间的通信。要让开发人员高效地使用 API，就必须有详尽易懂的文档。NSwag c# 和 IronPDF 是帮助 C# API 文档工作流程的两个有效工具。本篇文章将讨论如何使用 NSwag 生成应用程序接口使用 .NET Core 编写规范，并使用 IronPDF 根据这些规范制作高质量的 PDF 文档。

如何在 C&num 中使用 NSwag；

1.使用 Swagger UI 创建静态网络 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 规范。通过检查 API 代码的结构，NSwag 可生成涵盖 API 端点、请求/响应形式、身份验证技术等内容的全面文档。

连接到 .NET 项目

通过将 NSwag 与 .NET 项目集成，开发人员可以轻松地将 Swagger 生成纳入开发流程。开发人员可将 NSwag 添加到.NET core 项目中，确保文档与代码库同步更新，每次构建项目时，NSwag 都会自动生成 Swagger 规范。

个性化和扩展

借助 NSwag 提供的广泛定制可能性，开发人员可以轻松调整生成的 Swagger 规范，以满足他们的独特需求。开发人员可以通过配置设置和注释控制生成文档的许多组件，包括响应代码、参数解释和路由命名约定。

开始使用 Nswag

在 C&num 中设置 Nswag；控制台应用程序

Nswag 基类库包括核心、注释和代码生成命名空间，可通过从 Nuget 安装获得。将 NSwag 集成到 C# 应用程序中以生成代码和 Swagger 规范，以及 NSwag 如何提高开发流程的效率。

Nswag C#（如何为开发人员工作）：图 1 - 在 Visual Studio 软件包管理器中浏览并安装 Nswag

在 Windows 控制台和窗体中实施 Nswag

通过自动客户端生成功能，开发人员可以在 Windows 桌面应用程序中集成 NSwag，从而高效地生成直接从桌面应用程序访问 API 的代码。在开发与在线服务或 RESTful API 通信的桌面应用程序时，NSwag 可以提供相当大的帮助。

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

VB C#

对于我们希望使用的 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 规范，并使用 IronPDF 将其转换为 PDF，从而制作出全面的、离线就绪的网络 API 文档，并可随时使用和共享。文献资料.以下程序是整合过程的一部分：

安装 IronPDF

启动 Visual Studio 项目。
选择 "工具">"NuGet 包管理器">"包管理器控制台"。
打开命令提示符，在 "软件包管理器控制台 "中键入以下命令：

Install-Package IronPdf

您也可以使用 NuGet Package Manager for Solutions 安装 IronPDF。
您可以从搜索结果中搜索并选择 IronPDF 软件包，然后点击 "安装 "选项。Visual Studio 将代为处理下载和安装。
NuGet 将安装 IronPDF 软件包和项目所需的任何依赖项。
安装完成后，IronPDF 即可用于您的项目。

通过 NuGet 网站安装

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

利用 DLL 进行安装

另外，您也可以使用 IronPDF 的 DLL 文件将其直接集成到您的项目中。要下载包含 DLL 的 ZIP 文件，请点击此处链接.解压文件并将 DLL 添加到您的项目中。

获取包含 DLL 的 ZIP 文件。解压缩后，将 DLL 加入项目中。

实施逻辑

通过使用 NSwag，开发人员可以结合 IronPDF 使用 "CodeGeneration.CSharp "更快地创建 API 文档和使用 API 的客户端代码。以下步骤是集成工作流程的一部分：

生成客户端代码： 要根据 Swagger 规范创建 C# 客户端代码，请使用 NSwag.CodeGeneration.CSharp。在此步骤中，与 API 端点通信的客户端类和方法的创建将自动完成。
利用 NSwag 获取数据： 使用 CodeGeneration.CSharp从 Swagger 规范生成 JSON 文档。在此阶段，请求/响应格式、身份验证技术和 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()

VB C#

上面的代码访问从结果对象中获取的数据，并在一个循环中将字段 Date、TemperatureF、TemperatureC 和 Summary 附加到段落中。然后指定 PDF 的输出文件路径，然后通知用户已成功生成 PDF。

以下是上述代码的结果。

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

结论

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

LiteLicense' Lite 捆绑包包括永久许可证、一年的软件维护和库的升级。IronPDF 提供免费许可，但对再分发和时间有限制。用户可以在试用期间评估解决方案，而无需查看水印。有关价格和许可证的更多信息，请参阅 IronPDF 的许可证。页码.转到此页了解有关 Iron Software 的更多信息图书馆.

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

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