訊息圖示
跳過到頁腳內容
  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套件管理器控制台來完成此操作：

Install-Package Swashbuckle.AspNetCore

或使用.NET CLI：

dotnet add package Swashbuckle.AspNetCore
dotnet add package Swashbuckle.AspNetCore
SHELL

步驟 2：配置斜撐桿

接下來，您需要在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套件管理器安裝的步驟：

  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 通過提供一種標準化的方法來定義和文檔化 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 天試用→完整產品。無限制。無需信用卡。 開始免費試用

Iron Support Team

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