[ASP.NET Core] WebApi with Swagger - 1. API 설명 추가하기 - 1

WebApi 프로젝트를 생성하면 기본적으로 Swagger 관련 라이브러리가 Injection 되어있다. 해당 라이브러리를 통해 Swagger 문서를 생성할 수 있는데, 그냥 기본 설정값만 쓴다면 Swagger를 제대로 이용할 수 없다.

이번 단계를 통해 Swagger를 한층 더 "고오급스럽게" 사용하여 클라이언트쪽 개발자들에게 보다 쉬운 소스 설명과 더 나아가 소스 자동화 기능을 통해 덜 일하고, 더 받아가는(?) 즐거운 개발생활을 즐길 수 있길 바란다.

swagger_1_comments 란 이름의 ASPNET Core WebApi 프로젝트 생성 후 아래와 같이 수행하자.

1. GenerateDocumentationFile 옵션 추가

프로젝트파일(.csproj)에 <GenerateDocumentationFile> 옵션을 true로 추가한다. 해당 옵션을 추가하게 되면 소스코드 주석이 빌드할때마다 xml 문서로 출력된다.

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.2.3" />
  </ItemGroup>

</Project>

2. 주석 추가

기본 생성된 WeatherForecastController에 아래와 같이 주석을 추가한다.

using Microsoft.AspNetCore.Mvc;

namespace swagger_1_comments.Controllers;

/// <summary>
/// 날씨 데이터를 제공하는 컨트롤러입니다.
/// </summary>
[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;

    /// <summary>
    /// 
    /// </summary>
    /// <param name="logger"></param>
    public WeatherForecastController(ILogger<WeatherForecastController> logger)
    {
        _logger = logger;
    }

    /// <summary>
    /// 날씨 데이터를 모두 가져옵니다.
    /// </summary>
    /// <returns></returns>
    [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();
    }
}

3. AddSwaggerGen 수정

builder.Services.AddSwaggerGen() 함수에 옵션을 받는 람다 함수를 아래와 같이 추가한다. 1단계에서 추가한 xml 문서를 읽어 Swagger 문서의 설명서로 추가하는 작업이다.

위 코드는 xml 출력위치를 별도로 수정하지 않았다는 전제하에 작성한 코드이다. xml 출력위치를 특정위치로 수정했다면 그에 맞는 경로를 참조할 수 있도록 해야한다.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    c.IncludeXmlComments($"{AppContext.BaseDirectory}/{프로젝트명}.xml", true);
});

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();

3단계 작업을 거치고난 뒤, dotnet run 명령어 또는 Visual Studio의 디버그키(보통 F5이다.)를 눌러 실행하면 주석이 설명문구로 붙은 Swagger 문서를 확인할 수 있다.

 

 

소스코드

learn-aspnetcore-webapi/src/swagger-1-comments at main · ddochea0314/learn-aspnetcore-webapi (github.com)