IRONSOFTWAREHOME
IRONSUITE10개 모두 2개 가격으로!
이미징 및 인식
Enterprise를 선택해야 하는 이유
영업 문의
기업별
전문가 네트워크에 참여하세요
개발자 업데이트

Swashbuckle ASP .NET Core (개발자를 위한 작동 원리)

제이콥 멜러, 팀 아이언 최고기술책임자
Jacob Mellor
Updated: 2026년 4월 21일

Swashbuckle은 RESTful 웹 API를 자동으로 문서화하는 C# .NET Core NuGet 패키지입니다. 이 블로그에서는 Swashbuckle ASP.NET Core와 IronPDF 설치 지침 NuGet 패키지를 살펴보고, 현대적인 ASP.NET Core 웹 API 개발을 가능하게 합니다. 함께 최소한의 코드로 달성할 수 있는 다양한 기능들을 제공합니다.

API 문서 페이지는 Web API 프로젝트에서 생성된 swagger.json 파일을 사용하는 Swagger UI 도구를 통해 표시됩니다. 생성된 JSON 문서는 오픈 API 표준을 따릅니다. Swashbuckle은 NuGet 패키지 Swashbuckle.AspNetCore으로 제공되며, 설치 및 구성하면 Swagger JSON을 자동으로 노출합니다. Swagger UI 도구는 API에 작성된 XML 주석에서 생성된 Swagger JSON 파일을 읽습니다. 추가적으로 프로젝트 설정 파일에서 활성화하여 XML 문서 파일을 생성할 수 있습니다. XML 주석은 XML 문서 파일로 변환되며, 여기서 Swagger JSON이 생성됩니다. 그런 후 Swagger 미들웨어가 JSON을 읽고 Swagger JSON 엔드포인트를 노출합니다.

.NET Core 웹 API 프로젝트에서 구현

웹 API 프로젝트를 시작해 봅시다:

dotnet new webapi -n SwashbuckleDemo
cd SwashbuckleDemo
dotnet build
dotnet add package Swashbuckle.AspNetCore --version 6.5.0
dotnet build
SHELL

여기서 'SwashbuckleDemo'라는 웹 API 프로젝트를 생성한 후 패키지 관리자 콘솔을 사용하여 .NET Core 웹 API 프로젝트에 Swashbuckle 패키지를 설치합니다.

Swagger 미들웨어 구성

Swagger 서비스를 Startup.cs 파일에서 구성하십시오.

using System.Reflection;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Builder;

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        // Other service configurations...

        // Register the Swagger generator
        services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });

            // Optionally, include XML comments for additional information
            var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
            var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
            c.IncludeXmlComments(xmlPath);
        });
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        // Other app configurations...

        // Enable middleware to serve generated Swagger as a JSON endpoint.
        app.UseSwagger();

        // Enable Swagger UI (HTML, JS, CSS, etc.), specifying the Swagger JSON endpoint.
        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
        });
    }
}

할 일을 목록 API에 대한 컨트롤러를 추가하십시오:

using Microsoft.AspNetCore.Http.HttpResults;
using Microsoft.AspNetCore.Builder;
using Microsoft.EntityFrameworkCore;
using Microsoft.AspNetCore.Mvc;
using System.Threading.Tasks;

// Example to define an entity class
public class Todo
{
    public int Id { get; set; }
    public string Name { get; set; }
    public bool IsComplete { get; set; }
}

// Example to define a DbContext class
public class TodoDb : DbContext
{
    public DbSet<Todo> Todos => Set<Todo>();
}

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "SwashbuckleDemo!");

app.MapGet("/todoitems", async (TodoDb db) =>
    await db.Todos.ToListAsync());

app.MapGet("/todoitems/complete", async (TodoDb db) =>
    await db.Todos.Where(t => t.IsComplete).ToListAsync());

app.MapGet("/todoitems/{id}", async (int id, TodoDb db) =>
    await db.Todos.FindAsync(id) is Todo todo
        ? Results.Ok(todo)
        : Results.NotFound());

app.MapPost("/todoitems", async (Todo todo, TodoDb db) =>
{
    db.Todos.Add(todo);
    await db.SaveChangesAsync();
    return Results.Created($"/todoitems/{todo.Id}", todo);
});

app.MapPut("/todoitems/{id}", async (int id, Todo inputTodo, TodoDb db) =>
{
    var todo = await db.Todos.FindAsync(id);
    if (todo is null) return Results.NotFound();
    todo.Name = inputTodo.Name;
    todo.IsComplete = inputTodo.IsComplete;
    await db.SaveChangesAsync();
    return Results.NoContent();
});

app.MapDelete("/todoitems/{id}", async (int id, TodoDb db) =>
{
    if (await db.Todos.FindAsync(id) is Todo todo)
    {
        db.Todos.Remove(todo);
        await db.SaveChangesAsync();
        return Results.Ok(todo);
    }

    return Results.NotFound();
});

app.Run();

다음과 같은 방식으로 컨트롤러를 추가할 수 있습니다:

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using System.Collections.Generic;
using System;
using System.Linq;

namespace RestFullMinimalApi.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;
        }

        /// <summary>
        /// Retrieves WeatherForecast
        /// </summary>
        /// <remarks>Awesomeness!</remarks>
        /// <response code="200">Retrieved</response>
        /// <response code="404">Not found</response>
        /// <response code="500">Oops! Can't lookup your request right now</response>
        [HttpGet(Name = "GetWeatherForecast")]
        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();
        }
    }

    public class WeatherForecast
    {
        public DateTime Date { get; set; }
        public int TemperatureC { get; set; }
        public string Summary { get; set; }
    }
}

위 코드는 GitHub - Swashbuckle Demo에서 확인할 수 있습니다.

Swashbuckle은 다음과 같은 기능을 제공합니다

Swagger UI 도구

Swashbuckle ASP .NET Core (개발자를 위한 작동 방식): 그림 1 - Swagger UI 도구

Swagger UI는 웹 API 응용 프로그램의 기본 URL에서 "/swagger/index.html"로 제공됩니다. 코드에 있는 모든 REST API를 나열합니다. Swagger 생성기는 JSON 파일을 읽고 UI에 반영합니다.

Swagger JSON

Swashbuckle.AspNetCore는 API의 구조에 대한 정보, 엔드포인트, 요청 및 응답 유형 등의 세부 사항을 포함한 Swagger JSON 파일을 자동으로 생성합니다. 이 JSON 파일은 Swagger/OpenAPI 표준을 지원하는 다른 도구와 서비스에서 사용할 수 있습니다.

Swagger JSON 파일은 웹 API 애플리케이션의 기본 URL에서 "/swagger/v1/swagger.json"에 있습니다.

Swashbuckle ASP .NET Core (개발자를 위한 작동 방식): 그림 2 - Swagger JSON 파일.

코드 주석

개발자는 ASP.NET Core 컨트롤러 내에서 XML 주석과 속성을 사용하여 Swagger 문서에 추가 정보를 제공할 수 있습니다. 여기에는 생성된 Swagger 문서를 개선하는 설명, 예시 및 기타 메타데이터가 포함됩니다.

[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;
    }

    /// <summary>
    /// Retrieves WeatherForecast
    /// </summary>
    /// <remarks>Awesomeness!</remarks>
    /// <response code="200">Retrieved</response>
    /// <response code="404">Not found</response>
    /// <response code="500">Oops! Can't lookup your request right now</response>
    [HttpGet(Name = "GetWeatherForecast")]
    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();
    }
}

구성 옵션

Swashbuckle.AspNetCore는 Swagger 문서 생성 방식을 사용자 정의할 수 있는 다양한 구성 옵션을 제공합니다. 개발자는 어떤 API가 문서화되는지를 제어하고, 명명 규칙을 구성하며, 다른 설정을 조정할 수 있습니다.

Swashbuckle.AspNetCore가 제공하는 주요 구성 옵션은 다음과 같습니다:

SwaggerGen 옵션

c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });

이 줄은 Swagger 문서 버전을 지정하고 API의 제목 및 버전과 같은 메타데이터를 포함합니다.

c.IncludeXmlComments(xmlPath);

이 옵션은 코드의 XML 주석을 포함하여 Swagger 문서에 추가 정보를 제공할 수 있게 합니다. xmlPath 변수가 XML 주석 파일의 위치를 가리키고 있어야 합니다.

c.DescribeAllParametersInCamelCase();

이 옵션은 매개 변수 이름에 camelCase를 사용하도록 Swagger 생성기를 구성합니다.

c.OperationFilter<CustomOperationFilter>();

특정 작업에 대해 Swagger 문서를 수정하기 위해 사용자 정의 작업 필터를 등록할 수 있습니다. CustomOperationFilter는 IOperationFilter을 구현하는 클래스입니다.

Swagger UI 옵션

c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");

이 줄은 Swagger UI가 문서를 표시하도록 구성합니다. 첫 번째 매개변수는 Swagger JSON 파일의 URL이고, 두 번째 매개변수는 사용자가 친숙한 API 버전 이름입니다.

c.RoutePrefix = "swagger";

Swagger UI의 경로 접두사를 설정할 수 있습니다. 이 예에서 Swagger UI는 /swagger에서 사용할 수 있습니다.

c.DocExpansion(DocExpansion.None);

이 옵션은 Swagger UI가 API 문서를 표시하는 방식을 제어합니다. DocExpansion.None는 기본적으로 모든 작업을 접습니다.

SwaggerOptions

c.SerializeAsV2 = true;

이 옵션은 Swagger 문서를 버전 2.0 형식(true) 또는 3.0 형식(false)으로 직렬화할지를 지정합니다. Swagger 2.0을 사용하려면 true로 설정하십시오.

c.DisplayOperationId();

이 옵션은 Swagger UI에 작업 ID를 표시하여 디버깅 및 API 구조 이해에 유용할 수 있습니다.

c.OAuthClientId("swagger-ui");

API가 OAuth 인증을 사용하는 경우 Swagger UI에 대한 OAuth 클라이언트 ID를 구성할 수 있습니다.

이것들은 사용 가능한 구성 옵션의 몇 가지 예일 뿐입니다. Swashbuckle.AspNetCore 라이브러리는 매우 사용자 정의 가능하며, 다양한 옵션과 필터를 결합하여 특정 요구에 맞게 Swagger 문서를 조정할 수 있습니다. 항상 공식 문서나 개발 환경의 IntelliSense를 참조하여 사용 가능한 옵션에 대한 최신 및 포괄적인 정보를 확인하십시오.

IronPDF 소개

IronPDF 제품 개요는 PDF 문서를 읽고 생성하는 데 도움이 되는 Iron Software 웹사이트의 C# PDF 라이브러리입니다. 스타일 정보가 포함된 포맷 문서를 쉽게 PDF로 변환할 수 있습니다. IronPDF는 HTML 콘텐츠에서 손쉽게 PDF를 생성할 수 있습니다. URL에서 HTML 콘텐츠를 다운로드한 다음 PDF를 생성할 수 있습니다.

IronPDF는 웹 페이지, URL 및 HTML을 PDF로 변환하는 데 탁월하며 소스를 완벽하게 재현합니다. 보고서 및 송장과 같은 온라인 콘텐츠의 PDF 생성을 위해 이상적이며, 어떤 웹페이지의 PDF 버전을 손쉽게 생성합니다.

using IronPdf;

class Program
{
    static void Main(string[] args)
    {
        var renderer = new ChromePdfRenderer();

        // 1. Convert HTML String to PDF
        var htmlContent = "<h1>Hello, IronPDF!</h1><p>This is a PDF from an HTML string.</p>";
        var pdfFromHtmlString = renderer.RenderHtmlAsPdf(htmlContent);
        pdfFromHtmlString.SaveAs("HTMLStringToPDF.pdf");

        // 2. Convert HTML File to PDF
        var htmlFilePath = "path_to_your_html_file.html"; // Specify the path to your HTML file
        var pdfFromHtmlFile = renderer.RenderHtmlFileAsPdf(htmlFilePath);
        pdfFromHtmlFile.SaveAs("HTMLFileToPDF.pdf");

        // 3. Convert URL to PDF
        var url = "http://ironpdf.com"; // Specify the URL
        var pdfFromUrl = renderer.RenderUrlAsPdf(url);
        pdfFromUrl.SaveAs("URLToPDF.pdf");
    }
}

설치

NuGet을 통해 IronPDF 설치는 NuGet 패키지 관리자 정보 또는 Visual Studio 설치 가이드 패키지 관리자 콘솔을 사용합니다.

패키지 관리자 콘솔에 명령어를 입력하십시오:

PM > Install-Package IronPdf

Visual Studio 사용

![Swashbuckle ASP .NET Core (개발자를 위한 작동 방식): 그림 3 - Visual Studio에서 프로젝트를 엽니다. 도구 메뉴로 이동하여 "NuGet 패키지 관리자"를 선택한 후 "솔루션용 NuGet 패키지 관리"를 선택합니다. NuGet 패키지 관리자 인터페이스에서 Browe 탭에서 "IronPDF" 패키지를 검색하십시오. 그런 다음 최신 버전의 IronPDF를 선택하고 설치합니다.(/static-assets/pdf/blog/swashbuckle-asp-net-core/swashbuckle-asp-net-core-3.webp)

이제 웹사이트 내용을 PDF 파일로 다운로드하는 기능을 애플리케이션에 추가해 보겠습니다.

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using IronPdf;
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;

namespace RestFullMinimalApi.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;
        }

        /// <summary>
        /// Retrieves WeatherForecast
        /// </summary>
        /// <remarks>Awesomeness!</remarks>
        /// <response code="200">Retrieved</response>
        /// <response code="404">Not found</response>
        /// <response code="500">Oops! Can't lookup your request right now</response>
        [HttpGet(Name = "GetWeatherForecast")]
        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();
        }

        /// <summary>
        /// Retrieves WeatherForecast as Pdf
        /// </summary>
        /// <remarks>Awesomeness!</remarks>
        /// <response code="200">Retrieved</response>
        /// <response code="404">Not found</response>
        /// <response code="500">Oops! Can't lookup your request right now</response>
        [HttpGet("download", Name = "DownloadWeatherForecast")]
        public IActionResult GetWeatherPdf()
        {
            var results = 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();

            var html = GetHtml(results);
            var renderer = new ChromePdfRenderer();
            var pdf = renderer.RenderHtmlAsPdf(html);
            var fileName = "WeatherReport.pdf";
            pdf.SaveAs(fileName);

            var stream = new FileStream(fileName, FileMode.Open);
            // Return the PDF file for download
            return new FileStreamResult(stream, "application/octet-stream") { FileDownloadName = fileName };
        }

        private static string GetHtml(WeatherForecast[] weatherForecasts)
        {
            string header = @"
<html>
<head><title>WeatherForecast</title></head>
<body>
<h1>WeatherForecast</h1>
";

            var footer = @"
</body>
</html>";

            var htmlContent = header;
            foreach (var weather in weatherForecasts)
            {
                htmlContent += $@"
    <h2>{weather.Date}</h2>
    <p>Summary: {weather.Summary}</p>
    <p>Temperature in Celsius: {weather.TemperatureC}</p>
    <p>Temperature in Fahrenheit: {weather.TemperatureF}</p>
";
            }
            htmlContent += footer;
            return htmlContent;
        }
    }

    public class WeatherForecast
    {
        public DateTime Date { get; set; }
        public int TemperatureC { get; set; }
        public string Summary { get; set; }
        
        public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
    }
}

여기서는 날씨 데이터를 사용하여 HTML 문자열을 생성하고, 그 문자열을 사용하여 PDF 문서를 만듭니다.

HTML 콘텐츠

Swashbuckle ASP .NET Core (개발자를 위한 작동 방식): 그림 4 - 날씨 예보에 대한 HTML 콘텐츠.

PDF 보고서는 이렇게 보입니다:

Swashbuckle ASP .NET Core (개발자를 위한 작동 방식): 그림 5 - HTML에서 PDF 출력 파일: WeatherReport.pdf

전체 코드는 GitHub에서 찾을 수 있습니다 - Swashbuckle 데모 소스 코드.
문서에는 체험판 라이선스에 대한 작은 워터마크가 있으며, 유효한 라이선스로 제거할 수 있습니다.

라이센스 (무료 체험 가능)

위의 코드가 작동하려면 라이선스 키가 필요합니다. 이 키를 appsettings.json 파일에 두십시오.

{
    "IronPdf": {
        "LicenseKey": "your license key"
    }
}
JSON

체험판 라이선스는 IronPDF 체험 등록을 완료한 개발자들에게 제공됩니다. 체험판 라이선스를 받기 위해 신용카드는 필요하지 않습니다. 이메일 주소를 등록하여 무료 체험판을 받으세요.

결론

Swashbuckle와 IronPDF를 이해하면 ASP.NET Core 애플리케이션에 API 문서화와 PDF 생성 기능을 효과적으로 통합할 수 있습니다. IronPDF는 또한 시작하기에 대한 포괄적인 문서와 다양한 PDF 생성 코드 예제를 제공합니다.

또한, 코딩 기술을 향상시키고 현대 애플리케이션 요건을 충족시키는 데 도움이 되는 Iron Software의 관련 소프트웨어 제품을 탐색할 수 있습니다.

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

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

...
더 읽어보기

관련 기사

IronPDF의 최신 업데이트로 전자 송장을 간소화하세요: PDF/A-3 준수 및 ZUGFeRD 지원
업데이트됨 2026년 4월 21일
IronPDF의 최신 업데이트로 전자 송장을 간소화하세요: PDF/A-3 준수 및 ZUGFeRD 지원
IronPDF의 최신 업데이트가 PDF/A-3 컴플라이언스 및 ZUGFeRD 지원을 가져와 전자 송장 워크플로를 간소화하는 방법을 발견하세요. 특히 유럽 지역 기업들이 규제 준수를 달성하고, 송장 처리를 자동화하며, 이 하이브리드 문서 형식으로 미래에 대비할 수 있는 방법에 대해 알아보세요. EU 송장 지침 이상의 요구를 충족하기에 완벽합니다!
더 읽어보기
Key in blue circle

무료 30일 체험 키를 즉시 받으세요.

Your trial license will be sent to your email address

제한 없음. 100% 무제한 이용. 신용카드 불필요.

bullet_checked신용카드나 계정 생성은 필요하지 않습니다.제한 없음. 100% 무제한 이용. 신용카드 불필요.
  • Logo Aetna
  • Logo NASA
  • Logo GE
  • Logo Porsche
  • Logo USDA
  • Logo Qatar
Join Millions of Engineers who’ve tried IronPDF
무료 라이브 데모를 예약하세요
Booking Badge

전 세계 수백만 엔지니어들이 신뢰하는 제품입니다.

Iron Software의 고객 로고
부담 없는 무료 상담을 받아보세요
아래 양식을 작성하시거나 sales@ironsoftware.com으로 이메일을 보내주세요.
고객님의 정보는 항상 비밀로 유지됩니다.
전 세계 수백만 엔지니어들이 신뢰하는 제품입니다.
Iron Software의 고객 로고
지금 바로 30일 무료 체험판 키를 받으세요.
신용카드나 계정 생성은 필요하지 않습니다.