외부 라이브러리가 포함된 Swagger 문서

여러 라이브러리를 사용하여 향후 사례를 위해 코드를 분할하는 것은 좋은 일입니다. 개인적으로 나는 로직을 분할하여 다른 프로젝트나 프로젝트의 일부에서 재사용할 수 있다면 이 작업을 좋아합니다.

적어도 나에게는 Entity Framework을 포함하는 데이터 모델을 분할하여 Console application, Blazor application 또는 API에서 참조하고 사용할 수 있도록 해야 합니다.

제가 작업을 수행하는 방법에 대한 예를 살펴보겠습니다. 이것은 몇 가지 애플리케이션이 있는 프로젝트의 스크린샷과 모든 모델이 있는 공유 라이브러리입니다.

이것은 각 속성과 클래스에 대한 summary 문서가 포함된 API 프로젝트에서 이동한 클래스의 예입니다.

namespace CustomLibrariesDocumentation.Models
{
    /// <summary>
    /// WeatherForecast class
    /// </summary>
    public class WeatherForecast
    {
        /// <summary>
        /// Gets or sets the Date
        /// </summary>
        public DateOnly Date { get; set; }

        /// <summary>
        /// Gets or sets the TemperatureC
        /// </summary>
        public int TemperatureC { get; set; }

        /// <summary>
        /// Gets or sets the TemperatureF
        /// </summary>
        public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);

        /// <summary>
        /// Gets or sets the Summary
        /// </summary>
        public string? Summary { get; set; }
    }
}

Console application를 참조하고 모델을 사용하기 시작하면 문서를 볼 수 있습니다. 이는 Visual Studio의 표준 기능이므로 여기에서 볼 수 있듯이 잘 작동합니다.

그러나 API를 참조하고 Swagger로 이동하면 요약 문서가 없습니다.

이 문제를 어떻게 해결하나요?

먼저, 라이브러리에서 XML 주석을 활성화해야 합니다. 이를 위해서는 프로젝트 설정을 업데이트하고 ``:

그러면 여기에서 볼 수 있듯이 빌드 폴더에 파일 확장자 xml로 끝나는 일부 파일이 생성됩니다.

이제 이 작업이 완료되었으므로 Program.cs에 몇 가지 항목을 추가해야 해당 파일을 읽을 수 있습니다. 이는 기본적으로 해당 프로젝트의 XML 정의만 로드하기 때문입니다.

이는 AddSwaggerGen 내부에 있는 IncludeXmlComments라는 메서드를 사용합니다.

아이디어는 xml 파일이 모두 있으면 해당 파일을 Swagger에 강제로 로드한다는 것입니다.

builder.Services.AddSwaggerGen(s =>
{
    // Comments
    var allXmlFiles = Directory.GetFiles(AppContext.BaseDirectory, "*.xml");

    foreach (string xmlFiles in allXmlFiles)
    {
        s.IncludeXmlComments(xmlFiles);
    }
});

간단히 말해, 빌드 디렉터리에서 xml 파일을 가져와 IncludeXmlComments 메서드를 사용하여 추가합니다.

이제 API를 다시 로드하고 문서를 볼 수 있는지 확인합니다.

그리고 우리가 문서를 볼 수 있다는 것을 알 수 있습니다!

도움이 되셨길 바라며, 궁금한 점이 있으시면 언제든지 연락주세요!