消息图标
跳至页脚内容
  1. IronPDF
  2. IronPDF博客
  3. .NET 帮助
  4. OpenAPI .NET
.NET 帮助

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

Jacob Mellor，Team Iron 的首席技术官
Jacob Mellor
已更新:

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

首先，您需要通过NuGet在Visual Studio中安装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

在此示例中，使用SwaggerResponse属性来提供端点的详细OpenAPI描述和响应代码。

输出

OpenAPI .NET（开发者如何使用）：图1 - 自定义注释输出

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

OpenAPI .NET（开发者如何使用）：图2 - 响应输出

IronPDF

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

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

  1. 在Visual Studio中打开您的ASP.NET项目并导航到"工具"菜单。
  2. 选择"NuGet包管理器"，然后单击"为解决方案管理NuGet包"。
  3. 在"浏览"选项卡中，搜索"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，Team Iron 的首席技术官
Jacob Mellor
  立即与工程团队聊天
首席技术官

Jacob Mellor 是 Iron Software 的首席技术官，也是一位开创 C# PDF 技术的有远见的工程师。作为 Iron Software 核心代码库的原始开发者，他从公司成立之初就开始塑造公司的产品架构，与首席执行官 Cameron Rimington 一起将公司转变为一家拥有 50 多名员工的公司，为 NASA、特斯拉和全球政府机构提供服务。

Jacob 拥有曼彻斯特大学土木工程一级荣誉工程学士学位（BEng）（1998-2001 年）。他的旗舰产品 IronPDF 和 Iron Suite for .NET 库在全球的 NuGet 安装量已超过 3000 万次，其基础代码继续为全球使用的开发人员工具提供动力。Jacob 拥有 25 年的商业经验和 41 年的编码专业知识，他一直专注于推动企业级 C#、Java 和 Python PDF 技术的创新，同时指导下一代技术领导者。

相关文章

30天试用 → 完整产品。无限制。无卡。 免费试用

Iron Support Team

We're online 24 hours, 5 days a week.
Chat
Email
Call Me