在生产环境中测试,无水印。
随时随地满足您的需求。
获得30天的全功能产品。
几分钟内就能启动并运行。
在您的产品试用期间,全面访问我们的支持工程团队。
在当今的软件开发环境中,API 是必不可少的,因为它们促进了各种软件系统和组件之间的通信。 为了让开发人员高效地使用 API,必须有详尽易懂的文档。 NSwag C# 和 IronPDF 是两个可以帮助 C# API 文档工作流程的有效工具。 这篇文章将讨论如何使用NSwag结合.NET Core生成API规范,并使用IronPDF从这些规范中生成高质量的PDF文档。
使用 Swagger UI 创建静态网络 API。
创建 C# 控制台应用程序。
安装 NSwag 库。
导入命名空间并创建对象。
将 Swagger JSON 处理为 C# 代码。
创建名为 NSwag 的 .NET Swagger 工具链,是为了更轻松地为使用 ASP.NET Web API、ASP.NET Core 或其他 .NET Framework 构建的 API 创建 Swagger 规范或 OpenAPI 文档。
NSwag 可以使用控制器、模型和 .NET 程序集来自动生成 Swagger 规范。 NSwag 通过检查 API 代码的结构,生成涵盖 API 端点、请求/响应形式、验证技术等内容的综合文档。
通过将 NSwag 与 .NET 项目集成,开发人员可以轻松地将 Swagger 生成纳入其开发流程。 开发人员可以通过在 .NET Core 项目中添加 NSwag 来确保文档与代码库同步更新,NSwag 会在每次构建项目时自动生成 Swagger 规范。
借助 NSwag 提供的广泛定制可能性,开发人员可以轻松调整生成的 Swagger 规范,以满足他们的独特需求。 开发人员可以通过配置设置和注释控制生成文档的许多组件,包括响应代码、参数解释和路由命名约定。
NSwag 基类库包括核心、注释和代码生成命名空间,应可通过从 NuGet 安装获得。 将 NSwag 集成到 C# 应用程序中以生成代码和 Swagger 规范,以及 NSwag 可如何提高开发流程的效率。
通过自动生成客户端,开发人员可以将 NSwag 集成到 Windows 桌面应用程序中,从而在桌面应用程序中直接高效地生成访问 API 的代码。 在开发与在线服务或 RESTful API 通信的桌面应用程序时,它可能会很有帮助。
NSwag 可用于网络应用程序,为内部 API 生成 API 文档,并为消费外部 API 生成客户端代码。这有助于开发人员保持应用程序前端和后端组件的一致性。
下面是一个代码示例,向您展示如何使用 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
。 要更改生成的客户端代码,我们调整代码生成器的设置(CSharpClientGeneratorSettings
)。 在本例中,指定了生成的客户端代码的类名和命名空间。
从加载的 Swagger 文档中,我们构造一个 CSharpClientGenerator
实例,并使用它生成客户端代码(client code)。 创建的客户端代码将保存到指定的输出路径。 我们会对程序中可能出现的任何异常或错误做出响应,并在控制台上显示相关通知。
NSwag 可以使用 Swagger 规范生成多种语言的客户端代码,包括 Java、TypeScript 和 C#。 这样,开发人员就可以在其应用程序中简单地使用 API。
以 Swagger 规范为基础,NSwag 还可以制作服务器代码,如 ASP.NET Core 控制器。 这有助于快速为实现 API 搭建服务器端代码脚手架。
根据 Swagger 规范,NSwag 可以制作交互式 API 文档,如 Swagger UI。 本文档提供了一个易于使用的界面,用于探索和测试 API 端点。
为了与基于 SOAP 的 API 集成,NSwag 可以制作代理类。 这样,程序员就可以使用制作的客户端代码在其应用程序中访问 SOAP 服务。
NSwag 能够验证 Swagger 规范,确保其符合 OpenAPI/Swagger 标准。 这样可以更容易地发现 API 文档中的任何错误或差异。
开发人员可以通过将 NSwag 与 IronPdf 集成,利用这两种技术的优势改进 API 文档的工作流程。 开发人员可以使用 NSwag 生成 Swagger 规范,并使用IronPDF 将其转换为 PDF,从而生成可随时使用和共享的完整离线 .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");
}
}
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
Install-Package IronPdf
探索并从搜索结果中选择 IronPdf 软件包,然后点击 "安装 "选项。 Visual Studio 将代表您处理下载和安装事宜。
有关IronPDF的功能、兼容性和可用下载的更多信息,请访问NuGet上的IronPDF页面。
或者,您可以通过使用其DLL文件直接将IronPDF集成到您的项目中。要下载包含DLL的ZIP文件,请单击IronPDF下载链接。 解压文件并将 DLL 添加到您的项目中。
要获取包含 DLL 的 ZIP 文件,请在解压缩后将 DLL 整合到您的项目中。
通过利用 NSwag,开发人员可以结合 IronPDF 使用CodeGeneration.CSharp
更快速地创建 API 文档和客户端代码。 以下步骤是集成工作流程的一部分:
生成客户端代码: 要从 Swagger 规范创建 C# 客户端代码,请使用 NSwag.CodeGeneration.CSharp
。 在这一步骤中,将自动创建与 API 端点通信的客户端类和方法。
利用 NSwag 获取数据:要从 Swagger 规格生成 JSON 文档,请使用CodeGeneration.CSharp
。 在这一阶段,请求/响应格式、身份验证技术和 API 客户端端点将被制作成人类可读的文档。
将 JSON 转换为 PDF:要将生成的代码结果转换为 PDF 文档,请使用 IronPDF。 在这一阶段,HTML 文本将被转换成经过润色的 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()
上述代码访问从结果对象中检索的数据,并在循环中将字段Date
、TemperatureF
、TemperatureC
和Summary
附加到段落中。然后指定PDF的输出文件路径,并通知用户PDF已成功生成。
以下是上述代码的结果。
CodeGeneration
NSwag 技术,如 CSharp
和 IronPDF 协同工作,以简化客户端代码生成和 API 文档编制流程。 通过将这些工具集成到 C# 应用程序中,开发人员可以加快 API 驱动型解决方案的创建速度,自动创建 API 文档,并制作出外观专业的 PDF 出版物。 NSwag.CodeGeneration.CSharp
与IronPDF结合使用,为开发人员提供了一套完整的解决方案,无论是在开发桌面、网络还是云端应用程序时,都能高效地记录API并生成C#客户端代码。
$749 Lite 套件包括一个永久许可证、一年的软件维护以及对库的升级。 IronPdf 提供免费授权,但对再分发和时间有限制。用户可以在试用期间对解决方案进行评估,而无需查看水印。 有关价格和许可的更多信息,请查看IronPDF 的许可信息。 请访问Iron Software 库页面以获取有关 Iron Software 产品库的更多信息。