信息圖標
跳過到頁腳內容
  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

首先，您需要在 Visual Studio 中透過 NuGet 安裝 Swashbuckle.AspNetCore 套件。 您可以使用 NuGet Package Manager Console 進行此工作：

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 (How It Works For Developers)：圖 1 - 自訂註解輸出

按一下執行按鈕，您會得到以下回應。

OpenAPI .NET (How It Works For Developers)：圖 2 - 回應輸出

IronPDF

IronPDF for ASP.NET 是一款功能強大的工具，可在 ASP.NET 應用程式中無縫生成和處理 PDF 文件。 憑藉其直觀的 API 和強大的功能，開發人員可以毫不費力地將 PDF 生成整合到他們的網路專案中，為使用者提供增強的文件管理功能。 無論是從頭開始建立 PDF、將 HTML 內容轉換為 PDF，或是新增圖片和文字等動態元素，IronPDF 都能簡化流程，確保高效且專業地生成文件。

使用 NuGet Package Manager 安裝的步驟：

1.在 Visual Studio 中開啟您的 ASP.NET 專案，並導航至"工具"功能表。 2.選擇 "NuGet Package Manager"，然後按一下 "Manage NuGet Packages for Solution"。 3.在"瀏覽"標籤中，搜尋"IronPDF"並選擇所需版本。 按一下"安裝"即可將套件新增至您的專案。 IronPDF for .NET 及其相依性將會自動下載與整合，讓您可以在 ASP.NET 應用程式中無縫地開始運用其功能。

OpenAPI .NET (How It Works For Developers)：圖 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 (How It Works For Developers)：圖 4 - API 輸出

下載並開啟隨附的 PDF 檔案。

OpenAPI .NET (How It Works For Developers)：圖 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 通過提供一種標準化的方法來定義和文檔化 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 文件。這種集成支持有效的文檔管理並豐富了應用程式的整體功能。

Jacob Mellor, Team Iron 首席技術官
Jacob Mellor
  立即與工程團隊聊天
首席技術官

Jacob Mellor是Iron Software的首席技術官，也是開創C# PDF技術的前瞻性工程師。作為Iron Software核心代碼庫的原始開發者，他自公司成立以來就塑造了公司的產品架構，並與CEO Cameron Rimington將公司轉型為服務NASA、Tesla以及全球政府機構的50多人公司。

Jacob擁有曼徹斯特大學土木工程一級榮譽學士學位（1998年–2001年）。他於1999年在倫敦開立首家軟體公司，並於2005年建立了他的第一個.NET組件，專注於解決Microsoft生態系統中的複雜問題。

他的旗艦作品IronPDF和Iron Suite .NET程式庫全球已獲得超過3000萬次NuGet安裝，他的基礎代碼不斷在全球各地驅動開發者工具。擁有25年以上的商業經驗和41年的編碼專業知識，Jacob仍然專注於推動企業級C#、Java和Python PDF技術的創新，同時指導下一代技術領導者。

相關文章

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

鋼鐵支援團隊

我們每週 5 天，每天 24 小時在線上。
聊天
電子郵件
打電話給我