.NET 帮助

OpenAPI .NET（对开发人员的工作原理）

已更新:六月 22, 2025

OpenAPI，前称为Swagger，是用于构建和描述RESTful API的规范。它允许开发者以标准化格式定义其API的结构，使各种工具和服务能够有效理解和交互REST API并提供反馈。在.NET生态系统中，通过多个库和工具简化OpenAPI .NET集成，使创建、记录和消费API更容易。

在本文中，我们将了解OpenAPI支持规范以及如何使用IronPDF创建PDF文件并将其作为API调用响应返回。

在.NET中设置OpenAPI

要开始OpenAPI .NET项目，通常使用Swashbuckle库，该库为ASP.NET Core API生成OpenAPI规范或文档。

步骤1：安装Swashbuckle

首先，需要通过Visual Studio中的NuGet安装Swashbuckle.AspNetCore包。您可以使用NuGet包管理器控制台来完成此操作：

Install-Package Swashbuckle.AspNetCore

或者使用.NET CLI：

dotnet add package Swashbuckle.AspNetCore

dotnet add package Swashbuckle.AspNetCore

SHELL

步骤2：配置Swashbuckle

接下来，需要在ASP.NET Core项目中配置Swashbuckle。这涉及到更新Program.cs文件以添加Swagger服务和配置Swagger中间件。

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllers();
// Configures Swagger/OpenAPI descriptions.
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllers();
// Configures Swagger/OpenAPI descriptions.
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
app.Run();

$vbLabelText $csharpLabel

生成和查看API文档

一旦配置了Swashbuckle，运行应用程序将自动生成OpenAPI文档。您可以通过导航到Swagger UI接口查看这些OpenAPI描述。

使用OpenAPI定义

OpenAPI定义是一种强大的工具，可用于生成客户端SDK、测试API以及确保不同服务之间的一致性。 OpenAPI规范定义了一个标准的、与语言无关的API接口，允许人类和计算机在不访问源代码的情况下理解服务的功能。

通过自定义注释扩展OpenAPI

Swashbuckle允许您通过自定义注释增强您的OpenAPI文档。这些注释可以直接添加到控制器和模型中，以提供有关API行为和数据结构的附加信息。

示例：自定义注释

using Microsoft.AspNetCore.Mvc;

namespace WebApplication8.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        private static readonly string[] Summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

        private readonly ILogger<WeatherForecastController> _logger;

        public WeatherForecastController(ILogger<WeatherForecastController> logger)
        {
            _logger = logger;
        }

        [HttpGet(Name = "GetWeatherForecast")]
        [SwaggerOperation(Summary = "Gets the weather forecast for the next 5 days")]
        [SwaggerResponse(200, "Successfully retrieved weather forecast")]
        public IEnumerable<WeatherForecast> Get()
        {
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            })
            .ToArray();
        }
    }
}

using Microsoft.AspNetCore.Mvc;

namespace WebApplication8.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        private static readonly string[] Summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

        private readonly ILogger<WeatherForecastController> _logger;

        public WeatherForecastController(ILogger<WeatherForecastController> logger)
        {
            _logger = logger;
        }

        [HttpGet(Name = "GetWeatherForecast")]
        [SwaggerOperation(Summary = "Gets the weather forecast for the next 5 days")]
        [SwaggerResponse(200, "Successfully retrieved weather forecast")]
        public IEnumerable<WeatherForecast> Get()
        {
            return Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            })
            .ToArray();
        }
    }
}

$vbLabelText $csharpLabel

在这个例子中，使用了SwaggerOperation和SwaggerResponse属性来提供详细的OpenAPI描述和端点的响应代码。

输出

OpenAPI .NET（对开发者的工作原理）：图1 - 自定义注释输出

点击执行按钮，您将获得以下响应。

OpenAPI .NET（对开发者的工作原理）：图2 - 响应输出

IronPDF。

IronPDF for ASP.NET是一种强大的工具，可以在ASP.NET应用程序中无缝生成和操作PDF文档。凭借其直观的API和强大的功能，开发者可以轻松地将PDF生成集成到他们的Web项目中，为用户提供增强的文档管理能力。无论是从头开始创建PDF，将HTML内容转换为PDF，还是添加诸如图像和文本之类的动态元素，IronPDF都简化了这一过程，确保高效和专业的文档生成。

使用NuGet包管理器安装步骤：

在Visual Studio中打开您的ASP.NET项目并导航到"工具"菜单。
选择"NuGet包管理器"，然后单击"为解决方案管理NuGet包"。
在"浏览"选项卡中，搜索"IronPDF"并选择所需版本。点击"安装"将包添加到您的项目。 IronPDF及其依赖项将自动下载和集成，允许您无缝地在ASP.NET应用程序中开始利用它的功能。

OpenAPI .NET（对开发者的工作原理）：图3 - IronPDF

响应API调用获取PDF文件

将以下代码添加到您的控制器文件中，它使用IronPDF创建一个PDF文件并将其作为API调用的响应返回。

using Microsoft.AspNetCore.Mvc;
using IronPdf;

namespace WebApplication8.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        private static readonly string[] Summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

        private readonly ILogger<WeatherForecastController> _logger;

        public WeatherForecastController(ILogger<WeatherForecastController> logger)
        {
            _logger = logger;
        }

        [HttpGet(Name = "GetWeatherForecast")]
        public IActionResult GetWeatherForecastPdf()
        {
            var htmlContent = @"
        <html>
        <head>
            <title>Weather Forecast</title>
        </head>
        <body>
            <h1>Weather Forecast</h1>
            <table>
                <tr>
                    <th>Date</th>
                    <th>Temperature (Celsius)</th>
                    <th>Summary</th>
                </tr>";

            var forecasts = Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            });

            // Iterate over the forecasts and add data to the HTML string
            foreach (var forecast in forecasts)
            {
                htmlContent += $@"
            <tr>
                <td>{forecast.Date.ToShortDateString()}</td>
                <td>{forecast.TemperatureC}</td>
                <td>{forecast.Summary}</td>
            </tr>";
            }

            htmlContent += @"
            </table>
        </body>
        </html>";

            // Convert the HTML string to a PDF using IronPDF
            var renderer = new ChromePdfRenderer();
            var pdfDocument = renderer.RenderHtmlAsPdf(htmlContent);

            // Retrieve the byte array of the generated PDF
            var pdfBytes = pdfDocument.BinaryData;
            // Return the PDF file to the client
            return File(pdfBytes, "application/pdf", "WeatherForecast.pdf");
        }
    }
}

using Microsoft.AspNetCore.Mvc;
using IronPdf;

namespace WebApplication8.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class WeatherForecastController : ControllerBase
    {
        private static readonly string[] Summaries = new[]
        {
            "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
        };

        private readonly ILogger<WeatherForecastController> _logger;

        public WeatherForecastController(ILogger<WeatherForecastController> logger)
        {
            _logger = logger;
        }

        [HttpGet(Name = "GetWeatherForecast")]
        public IActionResult GetWeatherForecastPdf()
        {
            var htmlContent = @"
        <html>
        <head>
            <title>Weather Forecast</title>
        </head>
        <body>
            <h1>Weather Forecast</h1>
            <table>
                <tr>
                    <th>Date</th>
                    <th>Temperature (Celsius)</th>
                    <th>Summary</th>
                </tr>";

            var forecasts = Enumerable.Range(1, 5).Select(index => new WeatherForecast
            {
                Date = DateTime.Now.AddDays(index),
                TemperatureC = Random.Shared.Next(-20, 55),
                Summary = Summaries[Random.Shared.Next(Summaries.Length)]
            });

            // Iterate over the forecasts and add data to the HTML string
            foreach (var forecast in forecasts)
            {
                htmlContent += $@"
            <tr>
                <td>{forecast.Date.ToShortDateString()}</td>
                <td>{forecast.TemperatureC}</td>
                <td>{forecast.Summary}</td>
            </tr>";
            }

            htmlContent += @"
            </table>
        </body>
        </html>";

            // Convert the HTML string to a PDF using IronPDF
            var renderer = new ChromePdfRenderer();
            var pdfDocument = renderer.RenderHtmlAsPdf(htmlContent);

            // Retrieve the byte array of the generated PDF
            var pdfBytes = pdfDocument.BinaryData;
            // Return the PDF file to the client
            return File(pdfBytes, "application/pdf", "WeatherForecast.pdf");
        }
    }
}

$vbLabelText $csharpLabel

OpenAPI .NET（对开发者的工作原理）：图4 - API输出

下载并打开附加的PDF文件。

OpenAPI .NET（对开发者的工作原理）：图5 - PDF输出

结论

OpenAPI，前称为Swagger，通过Swashbuckle等库在.NET生态系统中简化了RESTful API的设计和文档编制，便于为ASP.NET Core项目自动生成API文档。展示OpenAPI与IronPDF之间的协同作用，我们展示了如何利用IronPDF的功能从HTML内容生成PDF文件并将其作为API响应返回，丰富了ASP.NET应用程序的功能。通过采用OpenAPI标准并利用IronPDF的强大功能，开发者可以增强其API文档实践并为用户提供完善的、功能丰富的应用程序。

有关IronPDF许可的详细信息，请参阅IronPDF许可详情。另外，您可以浏览我们的HTML到PDF转换教程以获得更多指导。

常见问题解答

如何在 ASP.NET 应用程序中将 HTML 内容转换为 PDF？

您可以在 ASP.NET 应用程序中使用 IronPDF 将 HTML 内容转换为 PDF。利用 IronPDF 的功能，您可以将 HTML 字符串或文件渲染为 PDF 文档，然后可以作为 API 响应提供或保存以进行文档管理。

OpenAPI 在 .NET 生态系统中扮演什么角色？

OpenAPI 在 .NET 生态系统中通过提供一种标准化的方法来定义和记录 RESTful API 起到了至关重要的作用。这种集成通常通过像 Swashbuckle 这样的工具来实现，它帮助生成 OpenAPI 规范，并在 ASP.NET Core 项目中实现轻松的 API 消费。

如何使用 Swashbuckle 在 .NET 项目中设置 Swagger UI？

要使用 Swashbuckle 在 .NET 项目中设置 Swagger UI，请通过 NuGet 安装 Swashbuckle.AspNetCore 包。然后，在Program.cs文件中配置 Swagger 服务，并设置 Swagger 中间件以通过 Swagger UI 启用 API 文档的自动生成和访问。

如何在 .NET 中从 OpenAPI 定义生成客户端 SDK？

OpenAPI 定义可用于生成客户端 SDK，简化 API 调用的复杂性。在 .NET 中，可以使用像 Swashbuckle 这样的工具生成这些定义，然后可以与 AutoRest 等工具一起使用，以创建各种编程语言的客户端 SDK。

使用自定义注释在 OpenAPI 文档中有什么优势？

OpenAPI 文档中的自定义注释可增强 API 规范的清晰性和详细性。在 .NET 中，Swashbuckle 允许您使用 SwaggerOperation 和 SwaggerResponse 等属性添加描述和响应代码，使 API 文档对开发人员更加信息丰富并易于理解。

如何在 ASP.NET Core 中将 PDF 文件作为 API 响应交付？

您可以在 ASP.NET Core 中使用 IronPDF 将 PDF 文件作为 API 响应交付。使用 IronPDF 的渲染方法从 HTML 内容生成 PDF，并使用 ASP.NET Core 的 IActionResult 在 API 控制器操作中返回该 PDF 文件作为响应的一部分。

将 OpenAPI 与 PDF 生成工具结合起来为 ASP.NET 应用程序带来什么好处？

将像 IronPDF 这样的 OpenAPI 和 PDF 生成工具结合在 ASP.NET 应用程序中，提供了全面的 API 文档，并通过允许 API 返回专业的 PDF 文档来增强功能。这种集成支持高效的文档管理并丰富了应用程序的整体能力。

Jacob Mellor

立即与工程团队聊天

首席技术官

Jacob Mellor 是 Iron Software 的首席技术官，是 C# PDF 技术的先锋工程师。作为 Iron Software 核心代码库的原始开发者，自公司成立以来，他就塑造了公司的产品架构，并与首席执行官 Cameron Rimington 一起将其转变成一家公司，拥有50多人，服务于 NASA、特斯拉和全球政府机构。

Jacob 拥有曼彻斯特大学 (1998-2001) 的一级荣誉土木工程学士学位。1999 年在伦敦创办了自己的第一家软件公司，并于 2005 年创建了他的第一个 .NET 组件后，他专注于解决微软生态系统中的复杂问题。

他的旗舰 IronPDF 和 Iron Suite .NET 库在全球已获得超过 3000 万次的 NuGet 安装，其基础代码继续为全球使用的开发者工具提供支持。拥有 25 年商业经验和 41 年编程经验的 Jacob 仍专注于推动企业级 C#、Java 和 Python PDF 技术的创新，同时指导下一代技术领导者。

Humanizer C#（开发人员如何使用）

Microsoft.Extensions.Caching.Memory...

客户亮点：

开发者焦点：

网络研讨会：

OpenAPI .NET（对开发人员的工作原理）

在.NET中设置OpenAPI

步骤1：安装Swashbuckle

步骤2：配置Swashbuckle

生成和查看API文档

使用OpenAPI定义

通过自定义注释扩展OpenAPI

示例：自定义注释

输出

IronPDF。

响应API调用获取PDF文件

结论

常见问题解答

如何在 ASP.NET 应用程序中将 HTML 内容转换为 PDF？

OpenAPI 在 .NET 生态系统中扮演什么角色？

如何使用 Swashbuckle 在 .NET 项目中设置 Swagger UI？

如何在 .NET 中从 OpenAPI 定义生成客户端 SDK？

使用自定义注释在 OpenAPI 文档中有什么优势？

如何在 ASP.NET Core 中将 PDF 文件作为 API 响应交付？

将 OpenAPI 与 PDF 生成工具结合起来为 ASP.NET 应用程序带来什么好处？

OpenAPI .NET（对开发人员的工作原理）

在.NET中设置OpenAPI

步骤1：安装Swashbuckle

步骤2：配置Swashbuckle

生成和查看API文档

使用OpenAPI定义

通过自定义注释扩展OpenAPI

示例：自定义注释

输出

IronPDF。

响应API调用获取PDF文件

结论

常见问题解答

如何在 ASP.NET 应用程序中将 HTML 内容转换为 PDF？

OpenAPI 在 .NET 生态系统中扮演什么角色？

如何使用 Swashbuckle 在 .NET 项目中设置 Swagger UI？

如何在 .NET 中从 OpenAPI 定义生成客户端 SDK？

使用自定义注释在 OpenAPI 文档中有什么优势？

如何在 ASP.NET Core 中将 PDF 文件作为 API 响应交付？

将 OpenAPI 与 PDF 生成工具结合起来为 ASP.NET 应用程序带来什么好处？

相关文章

架起 CLI 简洁性与 .NET 的桥梁：使用 IronPDF for .NET 的 Curl DotNet

RandomNumberGenerator C#

C# String Equals（开发者用法）

下一步：开始免费 30 天试用

下一步：开始免费 30 天试用

深受全球数百万工程师信赖