.NET API 문서 자동화하기 Swagger 설정법

Swagger는 API 문서화를 자동으로 생성해주는 도구로, API의 명세를 JSON 형식으로 제공하여 API를 테스트할 수 있다.

1. Swagger 설치 및 초기 설정

먼저, 프로젝트에 Swashbuckle을 설치한다.

Swashbuckle은 Swagger를 ASP.NET Web API에 통합하기 위한 패키지

NuGet 패키지 설치

Visual Studio에서 NuGet 패키지 관리자를 열고 Swashbuckle 패키지를 설치한다.

Install-Package Swashbuckle

SwaggerConfig 클래스 생성

Swagger 설정을 관리할 SwaggerConfig 클래스를 생성한다.

이 클래스는 Swagger의 모든 설정을 포함하며, API 문서화와 관련된 다양한 설정을 정의

using Swashbuckle.Application;
using System.Web.Http;

[assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]

namespace WebApplication2
{
    public class SwaggerConfig
    {
        public static void Register()
        {
            GlobalConfiguration.Configuration
                .EnableSwagger(c =>
                {
                    c.Schemes(new[] { "http", "https" });
                    c.SingleApiVersion("v1", "TEST API");
                    c.PrettyPrint();

                    // API 엔드포인트를 그룹화하는 방법 정의
                    c.GroupActionsBy(apiDesc =>
                    {
                        var attribute = apiDesc.GetControllerAndActionAttributes<SwaggerControllerNameAttribute>();
                        return attribute.Any() ? attribute.First().ControllerName : apiDesc.ActionDescriptor.ControllerDescriptor.ControllerName;
                    });

                    // XML 주석 파일 포함 (API 주석을 Swagger에 포함)
                    c.IncludeXmlComments(string.Format(@"{0}\bin\WebApplication2.xml", System.AppDomain.CurrentDomain.BaseDirectory));

                    // 특정 속성을 Swagger 문서에서 제외하는 필터 추가
                    c.SchemaFilter<SwaggerExcludeFilter>();
                    c.DescribeAllEnumsAsStrings();
                })
                .EnableSwaggerUi(c =>
                {
                    c.DocumentTitle("TEST API");
                    c.DisableValidator();  // 기본 검증 비활성화
                });
        }
    }
}

Swagger 설정 등록 방법

1. Global.asax에서 직접 호출

Global.asax 파일에서 SwaggerConfig.Register() 메서드를 호출하여 Swagger 설정을 등록할 수 있다. 이는 애플리케이션이 시작될 때 설정이 적용되게 한다.

public class WebApiApplication : System.Web.HttpApplication
{
    protected void Application_Start()
    {
        GlobalConfiguration.Configure(WebApiConfig.Register);
        SwaggerConfig.Register();  // Swagger 설정 추가
    }
}

2. [assembly: PreApplicationStartMethod] 사용

또 다른 방법으로, [assembly: PreApplicationStartMethod] 특성을 사용하여 Swagger 설정을 자동으로 등록할 수 있다.

[assembly: PreApplicationStartMethod(typeof(SwaggerConfig), "Register")]

이 특성을 사용하면 애플리케이션이 시작되기 전에 SwaggerConfig.Register() 메서드가 자동으로 호출된다.

2. SwaggerExcludeFilter SwaggerControllerNameAttribute

SwaggerExcludeFilter

SwaggerExcludeFilter는 특정 속성을 Swagger 문서에서 제외하기 위한 필터로 문서화가 필요 없는 내부 속성을 Swagger 문서에서 제외하고자 할 때 사용한다.

구현

using Swashbuckle.Swagger;
using System;
using System.Linq;
using System.Reflection;

namespace WebApplication2.Filters
{
    [AttributeUsage(AttributeTargets.Property)]
    public class SwaggerExcludeAttribute : Attribute
    {
    }

    public class SwaggerExcludeFilter : ISchemaFilter
    {
        public void Apply(Schema schema, SchemaRegistry schemaRegistry, Type type)
        {
            if (schema?.properties == null || type == null) return;

            // SwaggerExcludeAttribute가 적용된 속성만 필터링
            var excludeProperties = type.GetProperties()
                .Where(prop => prop.GetCustomAttribute<SwaggerExcludeAttribute>() != null);

            foreach (var excludeProperty in excludeProperties)
            {
                // 필터링된 속성을 Swagger 문서에서 제거
                var foundKey = schema.properties.Keys
                    .FirstOrDefault(x => string.Equals(x, excludeProperty.Name, StringComparison.CurrentCultureIgnoreCase));

                if (!string.IsNullOrEmpty(foundKey))
                    schema.properties.Remove(foundKey);
            }
        }
    }
}

사용 방법

속성에 SwaggerExclude 특성을 적용하면 해당 속성이 Swagger 문서에 포함되지 않는다.

public class MyModel
{
    public string IncludedProperty { get; set; }

    [SwaggerExclude]
    public string ExcludedProperty { get; set; }
}

SwaggerControllerNameAttribute

SwaggerControllerNameAttribute는 API 컨트롤러의 이름을 그룹화하거나 분류하는 데 사용된다.

구현

using System;

namespace WebApplication2.Filters
{
    [AttributeUsage(AttributeTargets.Class, AllowMultiple = false)]
    public class SwaggerControllerNameAttribute : Attribute
    {
        public string ControllerName { get; private set; }

        public SwaggerControllerNameAttribute(string controllerName)
        {
            if (string.IsNullOrEmpty(controllerName))
                throw new ArgumentNullException(nameof(controllerName));

            ControllerName = controllerName;
        }
    }
}

사용 방법

컨트롤러 클래스에 SwaggerControllerName 특성을 적용하여 특정 이름으로 그룹화할 수 있다.

using System.Web.Http;
using WebApplication2.Filters;

namespace WebApplication2.Controllers
{
    [SwaggerControllerName("테스트 API")]
    public class ValuesController : ApiController
    {
        // API 메서드들...
    }
}

이렇게 하면 ValuesController는 "테스트 API"라는 이름 아래에 그룹화되어 Swagger UI에서 표시된다.