1. IronPDF
  2. IronPDF 部落格
  3. .NET 幫助
  4. OpenAPI .NET
.NET 幫助

OpenAPI .NET（適用於開發人員的工作原理）

發佈 2024年7月1日
分享:

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 規範或文檔。

第一步：安裝 Swashbuckle

首先，您需要通過 Visual Studio 中的 NuGet 安裝 Swashbuckle.AspNetCore 套件。您可以使用 NuGet 套件管理器主控台進行此操作：

Install-Package Swashbuckle.AspNetCore

或者使用 .NET CLI：

dotnet add package Swashbuckle.AspNetCore

第2步：配置 Swashbuckle

接下來，您需要在 ASP.NET Core 項目中配置 Swashbuckle。這涉及更新 Startup.cs 文件以添加 Swagger 服務並配置 Swagger 中介軟件。

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI description at https://aka.ms/aspnetcore/swashbuckle
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();
// Learn more about configuring Swagger/OpenAPI description at https://aka.ms/aspnetcore/swashbuckle
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()
' Learn more about configuring Swagger/OpenAPI description at https://aka.ms/aspnetcore/swashbuckle
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()
VB   C#

生成和查看API文件

配置Swashbuckle後，運行您的應用程式將自動生成OpenAPI文檔。您可以通過導航至Swagger UI來查看這些OpenAPI描述，通常可以通過http://localhost:5000/swagger訪問。

使用 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
VB   C#

在這個例子中，SwaggerOperation 和 SwaggerResponse 屬性被用來為端點提供詳細的 OpenAPI 描述和響應代碼。

輸出

OpenAPI .NET（對開發者的運作方式）：圖 1 - 自訂註解輸出

點擊執行按鈕，您將獲得以下回應。

OpenAPI .NET（開發人員的工作方式）：圖 2 - 回應輸出

IronPDF

IronPDF for ASP.NET 是一個強大的工具，能夠在 ASP.NET 應用程式中無縫生成和操作 PDF 文件。借助其直觀的 API 和強大的功能，開發人員可以輕鬆將 PDF 生成集成到其網頁專案中，為用戶提供增強的文檔管理功能。無論是從頭開始創建 PDF、將 HTML 內容轉換為 PDF，還是添加圖像和文字等動態元素，IronPDF 都簡化了這一過程，確保高效和專業的文檔生成。

使用 NuGet 套件管理器安裝的步驟：

  1. 在 Visual Studio 中打開您的 ASP.NET 專案，並導航到「工具」菜單。
  2. 選擇「NuGet 套件管理器」，然後點擊「為解決方案管理 NuGet 套件」。
  3. 在「瀏覽」標籤中，搜索「IronPDF」並選擇所需版本。點擊「安裝」將套件添加到您的專案中。IronPDF 及其依賴項將自動下載並集成，讓您能夠無縫地在您的 ASP.NET 應用程式中利用其功能。

OpenAPI .NET（對開發人員的運作方式）：圖 3 - IronPDF

獲取 PDF 文件以回應 API 呼叫

將以下程式碼添加到您的控制器文件中，它使用 IronPDF 來創建 PDF 文件並將 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)]
            });

            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 HTML to PDF
            var renderer = new ChromePdfRenderer();
            var pdfDocument = renderer.RenderHtmlAsPdf(htmlContent);

            // Return PDF file
            var pdfBytes = pdfDocument.BinaryData;
            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)]
            });

            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 HTML to PDF
            var renderer = new ChromePdfRenderer();
            var pdfDocument = renderer.RenderHtmlAsPdf(htmlContent);

            // Return PDF file
            var pdfBytes = pdfDocument.BinaryData;
            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))
			})

			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 HTML to PDF
			Dim renderer = New ChromePdfRenderer()
			Dim pdfDocument = renderer.RenderHtmlAsPdf(htmlContent)

			' Return PDF file
			Dim pdfBytes = pdfDocument.BinaryData
			Return File(pdfBytes, "application/pdf", "WeatherForecast.pdf")
		End Function
	End Class
End Namespace
VB   C#

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轉換詳細教程以獲得更多指導。

< 上一頁
Humanizer C#（開發人員如何使用）
下一個 >
Microsoft.Extensions.Caching.Memory 範例 (含 PDF) 在 C#
從NuGet 免費用於開發

安裝與 NuGet nuget.org/packages/IronPdf

PM > Install-Package IronPdf

報告問題

準備開始了嗎？ 版本: 2024.10 剛剛發布

免費 NuGet 下載 總下載次數： 10,993,239 查看許可證 >

免費獲取

30天試用序號 立即。

15天試用金鑰 立即。

bullet_checked不需要信用卡或帳戶註冊
試用表格已提交
成功。

您的試用金鑰應該在郵件中。
如果不是，請聯繫
support@ironsoftware.com

bullet_test在生产环境中测试
無浮水印
子彈日曆30天完整
功能性產品
bullet_support24/5 技術支援
試用期間支援

感謝您！

您的授權密鑰已發送到提供的電子郵件地址。聯絡我們

24小時升級優惠：

Save 50% 在一
專業 升級

去 專業 涵蓋10位開發人員
和無限專案。

小時

:

分鐘

:

秒钟

升級到專業版

升級

專業

$600 美元

$299 美元

  • 10 位開發人員
  • 10個地點
  • 10個專案
今天 唯一

5 個 .NET 產品只需 2 個價格

IronPDF IronOCR IronXL IronBarcode IronWebscraper

總套件價值：

$7,192 美元

升級價格

今天
唯一

$499 美元

24小時後

$1,098 美元