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 설치하기
먼저, NuGet을 통해 Visual Studio에서 Swashbuckle.AspNetCore 패키지를 설치해야 합니다. NuGet 패키지 관리자 콘솔을 사용하여 이렇게 할 수 있습니다:
Install-Package Swashbuckle.AspNetCore
.NET CLI를 사용하여:
dotnet add package Swashbuckle.AspNetCore
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();
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();
}
}
}
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
이 예제에서는 SwaggerOperation와 SwaggerResponse 속성을 사용하여 엔드포인트에 대한 상세한 OpenAPI 설명과 응답 코드를 제공합니다.
출력

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

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");
}
}
}
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로 변환하는 튜토리얼을 탐색할 수 있습니다.
자주 묻는 질문
ASP.NET 애플리케이션에서 HTML 콘텐츠를 PDF로 변환하는 방법은 무엇입니까?
ASP.NET 애플리케이션에서 IronPDF를 사용하여 HTML 콘텐츠를 PDF로 변환할 수 있습니다. IronPDF의 기능을 활용하여 HTML 문자열이나 파일을 PDF 문서로 렌더링할 수 있으며, 이는 API 응답으로 제공하거나 문서 관리 목적으로 저장할 수 있습니다.
.NET 생태계에서 OpenAPI의 역할은 무엇입니까?
.NET 생태계에서 OpenAPI는 RESTful API를 정의하고 문서화하는 표준화된 방법을 제공합니다. 이 통합은 Swashbuckle과 같은 도구를 통해 자주 촉진되어 OpenAPI 명세를 생성하고 ASP.NET Core 프로젝트 내에서 쉽게 API를 소비할 수 있도록 합니다.
Swashbuckle을 사용하여 .NET 프로젝트에서 Swagger UI를 설정하는 방법은 무엇입니까?
Swashbuckle을 사용하여 .NET 프로젝트에서 Swagger UI를 설정하려면 Swashbuckle.AspNetCore 패키지를 NuGet을 통해 설치하세요. 그런 다음 Program.cs 파일에 Swagger 서비스를 구성하고 Swagger UI를 통한 API 문서의 자동 생성 및 액세스를 활성화하기 위해 Swagger 미들웨어를 설정하세요.
.NET에서 OpenAPI 정의를 사용하여 클라이언트 SDK를 생성하는 방법은 무엇입니까?
OpenAPI 정의는 API 호출의 복잡성을 추상화하여 API 소비를 용이하게 하는 클라이언트 SDK를 생성하는 데 사용될 수 있습니다. .NET에서는 Swashbuckle과 같은 도구가 이러한 정의를 생성하고, 이를 통해 다양한 프로그래밍 언어에서 클라이언트 SDK를 생성할 수 있는 AutoRest와 같은 도구와 함께 사용할 수 있습니다.
OpenAPI 문서에서 커스텀 주석을 사용하는 이점은 무엇입니까?
OpenAPI 문서에서 커스텀 주석을 사용하면 API 명세의 명확성과 세부 사항이 향상됩니다. .NET에서는 Swashbuckle을 사용하여 SwaggerOperation 및 SwaggerResponse와 같은 속성을 사용하여 설명 및 응답 코드를 추가하여 API 문서를 보다 정보가 풍부하고 개발자가 이해하기 쉽게 만듭니다.
ASP.NET Core에서 PDF 파일을 API 응답으로 제공하는 방법은 무엇입니까?
IronPDF를 사용하여 ASP.NET Core에서 API 응답으로 PDF 파일을 제공할 수 있습니다. IronPDF의 렌더링 메서드를 사용하여 HTML 콘텐츠에서 PDF를 생성하고, ASP.NET Core의 IActionResult를 사용하여 API 컨트롤러 액션에서 PDF 파일을 응답의 일부로 출력합니다.
OpenAPI와 PDF 생성 도구를 결합하면 ASP.NET 애플리케이션에 어떤 이점을 제공합니까?
ASP.NET 애플리케이션에서 IronPDF와 같은 OpenAPI 및 PDF 생성 도구를 결합하면 포괄적인 API 문서를 제공하고, API가 전문적인 PDF 문서를 반환할 수 있게 하여 기능성을 향상시킵니다. 이 통합은 효율적인 문서 관리를 지원하고 애플리케이션의 전반적인 기능을 강화합니다.




