푸터 콘텐츠로 바로가기
.NET 도움말

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
SHELL

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()
$vbLabelText   $csharpLabel

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
$vbLabelText   $csharpLabel

이 예제에서는 SwaggerOperationSwaggerResponse 속성을 사용하여 엔드포인트에 대한 상세한 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 패키지 관리'를 클릭합니다. '찾아보기' 탭에서 '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");
        }
    }
}
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
$vbLabelText   $csharpLabel

OpenAPI .NET (개발자를 위한 작동 방식): 그림 4 - API 출력

첨부된 PDF 파일을 다운로드하고 열어보십시오.

OpenAPI .NET (개발자를 위한 작동 방식): 그림 5 - 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을 사용하여 SwaggerOperationSwaggerResponse와 같은 속성을 사용하여 설명 및 응답 코드를 추가하여 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 문서를 반환할 수 있게 하여 기능성을 향상시킵니다. 이 통합은 효율적인 문서 관리를 지원하고 애플리케이션의 전반적인 기능을 강화합니다.

제이콥 멜러, 팀 아이언 최고기술책임자
최고기술책임자

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

제이콥은 맨체스터 대학교에서 토목공학 학사 학위(BEng)를 최우등으로 취득했습니다(1998~2001). 1999년 런던에서 첫 소프트웨어 회사를 설립하고 2005년 첫 .NET 컴포넌트를 개발한 후, 마이크로소프트 생태계 전반에 걸쳐 복잡한 문제를 해결하는 데 전문성을 발휘해 왔습니다.

그의 대표 제품인 IronPDF 및 Iron Suite .NET 라이브러리는 전 세계적으로 3천만 건 이상의 NuGet 설치 수를 기록했으며, 그의 핵심 코드는 전 세계 개발자들이 사용하는 다양한 도구에 지속적으로 활용되고 있습니다. 25년의 실무 경험과 41년의 코딩 전문성을 바탕으로, 제이콥은 차세대 기술 리더들을 양성하는 동시에 기업 수준의 C#, Java, Python PDF 기술 혁신을 주도하는 데 주력하고 있습니다.

아이언 서포트 팀

저희는 주 5일, 24시간 온라인으로 운영합니다.
채팅
이메일
전화해