기존 자료를 참고해도 NuGet 패키지 찾기 어려움이 발생할 수 있어 직접 경험을 정리합니다.

프로젝트는 .NET 4.5 기반으로 진행하며 Swagger-Net과 Swashbuckle.Net45 패키지를 사용했습니다.

프로젝트 속성->빌드->출력에서 XML 문서 파일 생성 체크박스를 활성화합니다.

서비스 실행 후 다음 주소로 접근하면 됩니다:

프로젝트 주소/swagger/ui/index

메서드 주석이 존재하는 경우 API 문서가 정상적으로 표시됩니다.

이제 API 호출 방법을 살펴보겠습니다.

파라미터 없는 요청 예시:

파라미터가 필요한 요청 예시:

헤더 인증이 필요한 경우 처리 방법입니다. 인증 필터인 ApiAuthAttribute를 사용해 "auth" 헤더 존재 여부를 확인합니다.

protected override bool IsAuthorized(HttpActionContext actionContext)
        {
            var authHeaderValue = actionContext.Request.Headers
                .Where(h => h.Key == "auth")
                .Select(h => h.Value.FirstOrDefault())
                .FirstOrDefault();
            
            if (authHeaderValue != null)
            {
                string token = authHeaderValue;
                if (string.IsNullOrEmpty(token))
                {
                    var result = new HttpResponseMessage(HttpStatusCode.Unauthorized);
                    actionContext.Response = result;
                    return false;
                }
                return true;
            }
            return false;
        }

Swagger UI에 헤더 파라미터 추가를 위한 필터:

public class HeaderParameterFilter : IOperationFilter
    {
        public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
        {
            if (operation.parameters == null)
                operation.parameters = new List<Parameter>();
                
            var requiresAuth = apiDescription.ActionDescriptor
                .GetCustomAttributes<ApiAuthAttribute>().Any();
                
            if (requiresAuth)
            {
                operation.parameters.Add(new Parameter
                {
                    name = "auth",
                    @in = "header",
                    description = "인증 토큰(로그인 후 발급됨)",
                    required = false,
                    type = "string"
                });
            }
        }
    }

SwaggerConfig.cs 파일에서 설정 변경:

// HeaderParameterFilter 클래스 추가
c.OperationFilter<HeaderParameterFilter>();

설정 완료 후 Swagger UI를 새로고침하면 인증 헤더가 반영된 문서를 확인할 수 있습니다.