
OpenAPI .NET (개발자에게 어떻게 작동하는가)
OpenAPI, 이전에는 Swagger로 알려졌던, RESTful API를 구축하고 설명하는 사양입니다. 개발자가 API의 구조를 표준화된 형식으로 정의할 수 있어 다양한 도구와 서비스가 REST API를 효과적으로 이해하고 상호작용하며 피드백을 제공할 수 있게 합니다. .NET 생태계에서는 여러 라이브러리와 도구를 통해 OpenAPI .NET 통합이 용이해져, API를 생성, 문서화 및 소비하는 것이 더 쉬워졌습니다.
이 기사에서는 OpenAPI 지원 사양과 IronPDF를 사용하여 PDF 파일을 생성하고 이를 API 호출 응답으로 반환하는 방법을 배웁니다.
.NET에서 OpenAPI 설정하기
OpenAPI .NET 프로젝트를 시작하려면 일반적으로 ASP.NET Core API에 대한 OpenAPI 사양이나 문서를 생성하는 Swashbuckle 라이브러리를 사용합니다.
1단계: Swashbuckle 설치하기
먼저, Visual Studio에서 NuGet을 통해 Swashbuckle.AspNetCore 패키지를 설치해야 합니다. NuGet 패키지 관리자 콘솔을 사용하여 이렇게 할 수 있습니다:
.NET CLI를 사용하여:
dotnet add package Swashbuckle.AspNetCore
2단계: Swashbuckle 구성하기
그런 다음 ASP.NET Core 프로젝트에서 Swashbuckle을 구성해야 합니다. 이는 Swagger 서비스를 추가하고 Swagger 미들웨어를 구성하기 위해 Program.cs 파일을 업데이트하는 것을 포함합니다.
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()API 문서 생성 및 보기
Swashbuckle가 구성되면, 애플리케이션을 실행할 때 자동으로 OpenAPI 문서가 생성됩니다. 이러한 OpenAPI 설명을 보려면 Swagger UI 인터페이스로 이동하십시오.
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();
}
}
}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이 예제에서는, 엔드포인트에 대해 상세한 OpenAPI 설명과 응답 코드를 제공하기 위해 SwaggerOperation 및 SwaggerResponse 속성을 사용합니다.
출력

실행 버튼을 클릭하면 다음과 같은 응답을 받을 수 있습니다.

IronPDF
IronPDF for ASP.NET은 ASP.NET 애플리케이션 내에서 PDF 문서의 원활한 생성 및 조작을 가능하게 하는 강력한 도구입니다. 직관적인 API와 강력한 기능을 통해 개발자는 PDF 생성을 웹 프로젝트에 손쉽게 통합할 수 있으며, 사용자에게 향상된 문서 관리 기능을 제공합니다. 처음부터 PDF를 생성하거나 HTML 콘텐츠를 PDF로 변환하거나 이미지 및 텍스트와 같은 동적 요소를 추가할 때, IronPDF는 효율적이고 전문적인 문서 생성을 보장하여 프로세스를 단순화합니다.
NuGet 패키지 관리자를 사용하여 설치하는 단계:
- Visual Studio에서 ASP.NET 프로젝트를 열고 '도구' 메뉴로 이동합니다.
- 'NuGet 패키지 관리자'를 선택한 다음 '솔루션용 NuGet 패키지 관리'를 클릭합니다. '찾아보기' 탭에서 'IronPDF'를 검색하고 원하는 버전을 선택합니다. '설치'를 클릭하여 패키지를 프로젝트에 추가합니다. IronPDF 및 해당 종속성이 자동으로 다운로드 및 통합되어 ASP.NET 애플리케이션에서 기능을 원활하게 활용할 수 있습니다.

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");
}
}
}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
첨부된 PDF 파일을 다운로드하고 열어보십시오.

결론
OpenAPI, 이전에는 Swagger로 알려진, .NET 생태계에서 RESTful API 디자인 및 문서화를 Swashbuckle과 같은 라이브러리를 통해 간소화하여 ASP.NET Core 프로젝트의 자동 API 문서 생성을 촉진합니다. OpenAPI와 IronPDF 간의 시너지를 입증하기 위해 우리는 HTML 콘텐츠에서 PDF 파일을 생성하고 이를 API 응답으로 반환하여 ASP.NET 애플리케이션의 기능을 강화하는 IronPDF의 기능을 활용하는 방법을 시연했습니다. OpenAPI 표준을 수용하고 IronPDF의 강력한 기능을 활용함으로써 개발자는 API 문서화 관행을 개선하고 사용자에게 세련되고 기능이 풍부한 애플리케이션을 제공할 수 있습니다.
IronPDF 라이선스에 대한 자세한 정보는 IronPDF 라이선스 세부정보를 참조하십시오. 또한, 추가 안내를 위해 HTML을 PDF로 변환하는 튜토리얼을 탐색할 수 있습니다.

제이콥 멜러는 Iron Software의 최고 기술 책임자(CTO)이자 C# PDF 기술을 개척한 선구적인 엔지니어입니다. Iron Software의 핵심 코드베이스를 최초로 개발한 그는 창립 초기부터 회사의 제품 아키텍처를 설계해 왔으며, CEO인 캐머런 리밍턴과 함께 회사를 NASA, 테슬라, 그리고 전 세계 정부 기관에 서비스를 제공하는 50명 이상의 직원을 보유한 기업으로 성장시켰습니다.
관련 기사


