[ASP.NET Core] WebApi with Swagger - 2. 예제(example) 적용

Swagger 문서내 요청에서 파라메터에 어떤 값이 들어가야하는지, 또는 어떤 값이 나올지 주석을 이용해 제한적으로나마 예제(example)을 적용할 수 있다.

1. 숫자

/// <summary>
/// 입력된 일수만큼 날씨 데이터를 제공합니다.
/// </summary>
/// <param name="cnt" example="7">입력일수</param> // 숫자형 예제
/// <returns></returns>
[HttpGet("{cnt}", Name = "GetWeatherForecastByCount")]
public IEnumerable<WeatherForecast> Get(int cnt) {
    return Enumerable.Range(1, cnt).Select(index => new WeatherForecast
    {
        Date = DateTime.Now.AddDays(index),
        TemperatureC = Random.Shared.Next(-20, 55),
        Summary = Summaries[Random.Shared.Next(Summaries.Length)]
    })
    .ToArray();
}

숫자형 예시

2. 문자

/// <summary>
/// 입력한 요약에 해당하는 날씨 데이터를 제공합니다.
/// </summary>
/// <param name="summary" example="Freezing">입력한 날씨요약</param>
/// <returns></returns>
[HttpGet("summary", Name = "GetWeatherForecastBySummary")]
public IEnumerable<WeatherForecast> Get([FromQuery] string summary) {
    return Enumerable.Range(1, 100).Select(index => new WeatherForecast
    {
        Date = DateTime.Now.AddDays(index),
        TemperatureC = Random.Shared.Next(-20, 55),
        Summary = Summaries[Random.Shared.Next(Summaries.Length)]
    })
    .Where(x => summary == x.Summary)
    .ToArray();
}

문자형 예시

3. 날짜

/// <summary>
/// 오늘 ~ 입력한 날짜 하루전에 해당하는 날씨 데이터를 제공합니다.
/// </summary>
/// <param name="date" example="2023-02-14T00:00:00">입력날짜</param>
/// <returns></returns>
[HttpGet("datetime", Name = "GetWeatherForecastByDateTime")]
public IEnumerable<WeatherForecast> Get([FromQuery] DateTime date) {
    return Enumerable.Range(1, 100).Select(index => new WeatherForecast
    {
        Date = DateTime.Now.AddDays(index),
        TemperatureC = Random.Shared.Next(-20, 55),
        Summary = Summaries[Random.Shared.Next(Summaries.Length)]
    })
    .Where(x => (x.Date - date).TotalDays < 0)
    .ToArray();
}

날짜 예제

4. Boolean

/// <summary>
/// 짝수날만 가져올지, 아니면 홀수날만 가져올지 필터링하여 날씨 데이터를 제공합니다.
/// </summary>
/// <param name="isEven" example="false">짝수여부</param>
/// <returns></returns>
[HttpGet("bool", Name = "GetWeatherForecastByBool")]
public IEnumerable<WeatherForecast> Get([FromQuery] bool isEven) {
    return Enumerable.Range(1, 100).Select(index => new WeatherForecast
    {
        Date = DateTime.Now.AddDays(index),
        TemperatureC = Random.Shared.Next(-20, 55),
        Summary = Summaries[Random.Shared.Next(Summaries.Length)]
    })
    .Where(x => x.Date.Day % 2 == (isEven ? 0 : 1))
    .ToArray();
}

부울값 예제

이와 같이 단일형식의 파라메터는 example 속성으로 swagger에 예제를 추가시킬 수 있다. 단, Array와 같은 배열형식은 주석을 통해선 지원하지 않는다. (혹은 못찾았거나..)

Array를 예제로 꼭 제공해야할 경우, Swashbuckle.AspNetCore.SwaggerGen 에 속한 ParameterFilter 및 IParameterFilter를 써서 구현해줘야 할 수도 있다.

5. Object Type

사용자가 정의한 객체타입도 가능하다. 객체 타입의 경우 example 태그를 이용해 배열 정의도 가능하다.

/// <summary>
/// 입력한 DTO객체 요청에 해당하는 날씨 데이터를 제공합니다.
/// </summary>
/// <param name="req"></param>
/// <returns></returns>
[HttpGet("request", Name = "GetWeatherForecastByRequest")]
public IEnumerable<WeatherForecast> Get([FromQuery] WeatherForecastRequest req) {
    return Enumerable.Range(1, req.Cnt).Select(index => new WeatherForecast
    {
        Date = DateTime.Now.AddDays(index),
        TemperatureC = Random.Shared.Next(-20, 55),
        Summary = Summaries[Random.Shared.Next(Summaries.Length)]
    })
    .Where(x => req.Summaries!.Contains(x.Summary))
    .ToArray();
}

/// <summary>
/// 날씨 조회 Request Dto모델 입니다.
/// </summary>
public class WeatherForecastRequest
{
    /// <summary>
    /// 입력일수
    /// </summary>
    /// <example>7</example>
    public int Cnt { get; set; }
    
    /// <summary>
    /// 입력한 날씨요약
    /// </summary>
    /// <example>["Freezing", "Cold"]</example>
    public string[]? Summaries { get; set; }
}

개발자 정의 Type