信息圖標
跳過到頁腳內容
  1. IronPDF
  2. IronPDF博客
  3. .NET幫助
  4. OpenAPI .NET
.NET幫助

OpenAPI .NET（對於開發者的運行原理）

Curtis Chau
Curtis Chau
更新日期:

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();
Dim builder = WebApplication.CreateBuilder(args)

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

Dim app = builder.Build()

' Configure the HTTP request pipeline.
If app.Environment.IsDevelopment() Then
	app.UseSwagger()
	app.UseSwaggerUI()
End If

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();
        }
    }
}
Imports Microsoft.AspNetCore.Mvc

Namespace WebApplication8.Controllers
	<ApiController>
	<Route("[controller]")>
	Public Class WeatherForecastController
		Inherits ControllerBase

		Private Shared ReadOnly Summaries() As String = { "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" }

		Private ReadOnly _logger As ILogger(Of WeatherForecastController)

		Public Sub New(ByVal logger As ILogger(Of WeatherForecastController))
			_logger = logger
		End Sub

		<HttpGet(Name := "GetWeatherForecast")>
		<SwaggerOperation(Summary := "Gets the weather forecast for the next 5 days")>
		<SwaggerResponse(200, "Successfully retrieved weather forecast")>
		Public Function [Get]() As IEnumerable(Of WeatherForecast)
			Return Enumerable.Range(1, 5).Select(Function(index) New WeatherForecast With {
				.Date = DateTime.Now.AddDays(index),
				.TemperatureC = Random.Shared.Next(-20, 55),
				.Summary = Summaries(Random.Shared.Next(Summaries.Length))
			}).ToArray()
		End Function
	End Class
End Namespace
$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 包管理器安裝的步驟：

  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");
        }
    }
}
Imports Microsoft.AspNetCore.Mvc
Imports IronPdf

Namespace WebApplication8.Controllers
	<ApiController>
	<Route("[controller]")>
	Public Class WeatherForecastController
		Inherits ControllerBase

		Private Shared ReadOnly Summaries() As String = { "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching" }

		Private ReadOnly _logger As ILogger(Of WeatherForecastController)

		Public Sub New(ByVal logger As ILogger(Of WeatherForecastController))
			_logger = logger
		End Sub

		<HttpGet(Name := "GetWeatherForecast")>
		Public Function GetWeatherForecastPdf() As IActionResult
			Dim 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>"

			Dim forecasts = Enumerable.Range(1, 5).Select(Function(index) New WeatherForecast With {
				.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
			For Each forecast In forecasts
				htmlContent &= $"
            <tr>
                <td>{forecast.Date.ToShortDateString()}</td>
                <td>{forecast.TemperatureC}</td>
                <td>{forecast.Summary}</td>
            </tr>"
			Next forecast

			htmlContent &= "
            </table>
        </body>
        </html>"

			' Convert the HTML string to a PDF using IronPDF
			Dim renderer = New ChromePdfRenderer()
			Dim pdfDocument = renderer.RenderHtmlAsPdf(htmlContent)

			' Retrieve the byte array of the generated PDF
			Dim pdfBytes = pdfDocument.BinaryData
			' Return the PDF file to the client
			Return File(pdfBytes, "application/pdf", "WeatherForecast.pdf")
		End Function
	End Class
End Namespace
$vbLabelText   $csharpLabel

OpenAPI .NET（如何為開發人員提供服務）：圖 4 - API 輸出

下載並打開附加的 PDF 文件。

OpenAPI .NET（如何為開發人員提供服務）：圖 5 - PDF 輸出

結論

OpenAPI，以前稱為 Swagger，在 .NET 生態系統中通過像 Swashbuckle 這樣的庫簡化了 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 通過提供一種標準化的方法來定義和文檔化 RESTful API，在 .NET 生態系統中發揮著至關重要的作用。這種整合通常通過像 Swashbuckle 這樣的工具促進，該工具有助於生成 OpenAPI 規範並在 ASP.NET Core 項目中輕鬆使用 API。

如何在 .NET 項目中使用 Swashbuckle 設置 Swagger UI？

要在 .NET 項目中使用 Swashbuckle 設置 Swagger UI，請通過 NuGet 安裝 Swashbuckle.AspNetCore 包。然後，在您的 Program.cs 文件中配置 Swagger 服務，並設置 Swagger 中間件以啟用通過 Swagger UI 自動生成和訪問 API 文檔。

如何從 .NET 中的 OpenAPI 定義生成客戶端 SDK？

OpenAPI 定義可以用於生成客戶端 SDK，通過抽象 API 調用的複雜性來促進 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，並在您的 API 控制器操作中使用 ASP.NET Core 的 IActionResult 返回 PDF 文件作為響應的一部分。

將 OpenAPI 和 PDF 生成工具結合使用為 ASP.NET 應用程式帶來了哪些優勢？

在 ASP.NET 應用程式中將 OpenAPI 和像 IronPDF 這樣的 PDF 生成工具結合使用，提供了全面的 API 文檔，同時增強了功能，允許 API 返回專業的 PDF 文件。這種集成支持有效的文檔管理並豐富了應用程式的整體功能。

Curtis Chau
Curtis Chau
  立即與工程團隊聊天
技術作家

Curtis Chau 擁有卡爾頓大學計算機科學學士學位，專注於前端開發，擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面，喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。

除了開發之外，Curtis 對物聯網 (IoT) 有著濃厚的興趣，探索將硬體和軟體結合的創新方式。在閒暇時間，他喜愛遊戲並構建 Discord 機器人，結合科技與創意的樂趣。

相關文章

30 天試用→完整產品。無限制。無需信用卡。 開始免費試用