跳至頁尾內容
  1. IronPDF
  2. IronPDF博客
  3. .NET 幫助
  4. OpenAPI .NET
.NET 幫助

OpenAPI .NET（開發者使用指南）

Jacob Mellor，Team Iron 首席技術官
雅各·梅勒
更新:

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();
$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 (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");
        }
    }
}
$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 在 .NET 生態系統中扮演著至關重要的角色，它提供了一種標準化的方式來定義和記錄 RESTful API。這種整合通常藉助 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 是 Iron Software 的首席技術官，也是一位富有遠見的工程師，率先開發了 C# PDF 技術。作為 Iron Software 核心程式碼庫的最初開發者，他自公司成立之初便參與塑造了其產品架構，並與執行長 Cameron Rimington 一起將其發展成為一家擁有 50 多名員工、服務於 NASA、特斯拉和全球政府機構的公司。

Jacob 於 1998 年至 2001 年在曼徹斯特大學獲得土木工程一級榮譽學士學位。 1999 年，他在倫敦創辦了自己的第一家軟體公司；2005 年，他創建了自己的第一個 .NET 元件。此後，他專注於解決微軟生態系統中的複雜問題。

他的旗艦產品 IronPDF 和 IronSuite .NET 庫在全球 NuGet 上的安裝量已超過 3000 萬次，其基礎程式碼持續為全球開發者工具提供支援。憑藉 25 年的商業經驗和 41 年的程式設計專長，Jacob 始終致力於推動企業級 C#、Java 和 Python PDF 技術的創新，同時指導下一代技術領導者。

相關文章

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