[ASP.NET Core] WebApi with Swagger - 3. 응답 명세(ProducesResponseType)

항상 올바른 요청(Request)에 올바른 응답(Response)값만 줄 수 있는 상황이라면 좋겠지만, 요청이 거지같거나(?) 올바른 요청이지만 이를 제대로 제공할 데이터가 없는 경우가 종종 있다. ProducesResponseType는 이와 같이 응답상태에 따라 타입을 지정하여 안내할 수 있는 방법을 제공한다.

아래 소스코드는 데이터가 없을 땐 string 형식으로, 데이터가 있을땐 WeatherForecast 배열형식으로 이원화하여 응답할 수 있음을 안내하는 예제이다.

    /// <summary>
    /// 오늘 ~ 입력한 날짜 하루전에 해당하는 날씨 데이터를 제공합니다.
    /// </summary>
    /// <param name="date" example="2023-02-14T00:00:00">입력날짜</param>
    /// <returns></returns>
    [HttpGet("datetime", Name = "GetWeatherForecastByDateTime")]
    [ProducesResponseType(typeof(IEnumerable<WeatherForecast>), 200)]
    [ProducesResponseType(typeof(string), StatusCodes.Status404NotFound)] // 그냥 숫자 404로 써도 된다.
    public IActionResult Get([FromQuery] DateTime date) {
        var result = 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();

        if(result.Length == 0) {
            return NotFound("데이터 없음"); // 데이터가 없을 경우 404 Not Found 로 응답.
        }

        return Ok(result); // 정상적인 데이터를 응답해줄 수 있으므로 200 Ok 로 응답.
    }

데이터가 없음. (상태코드 : 404)

데이터가 있어 정상응답 (상태코드 : 200)

 

근데 해당기능은 쓸 때 이슈가 있다. 대한민국의 거의 대부분의 웹 API 개발에서 응답코드를 성공/실패 관계없이 200으로 보내주는 미친 짓이 대세이기 때문이다.

 

Http 상태코드(Status Code)값은 HTTP 프로토콜 "표준" 응답상태를 정의하는 코드값이다. 관련 코드에 대한 설명은 아래 사이트에서 확인 가능하다. 신규 개발시 "표준"을 지키도록 하자.

 

https://developer.mozilla.org/ko/docs/web/http/status

HTTP 상태 코드 - 위키백과, 우리 모두의 백과사전 (wikipedia.org)