3. CRUD 기능

3-2. 응답 타입

이 섹션에서는 API 엔드포인트에서 반환할 수 있는 다양한 HTTP 상태 코드를 문서화하는 방법을 다룹니다.

  1. 응답 유형 문서화:
    • GetPlant 엔드포인트에서는 BadRequest와 NotFound 상태 코드를 반환할 수 있습니다. 이러한 상태 코드를 Swagger 문서에 명시적으로 표시하기 위해 ProducesResponseType 어트리뷰트를 사용합니다.
  2. ProducesResponseType 어트리뷰트 사용:
    • ProducesResponseType 어트리뷰트를 사용하여 엔드포인트에서 반환할 수 있는 상태 코드를 문서화합니다. 예를 들어, 200 OK, 400 Bad Request, 404 Not Found 등을 명시할 수 있습니다.
  3. 응답 모델 명시:
    • ProducesResponseType 어트리뷰트에 type 매개변수를 추가하여 성공적인 응답의 경우 반환될 모델의 유형을 명시할 수 있습니다. 이를 통해 Swagger 문서에서 예상 응답 모델을 정확히 알 수 있습니다.
  4. 상태 코드 상수 사용:
    • StatusCodes 클래스의 상수를 사용하여 상태 코드를 명시함으로써 코드의 가독성을 높일 수 있습니다. 예를 들어, StatusCodes.Status200OK는 200보다 의미를 명확하게 전달합니다.
  5. 테스트 및 검증:
    • Swagger UI를 통해 엔드포인트를 테스트하면, 문서화된 상태 코드와 함께 예상 응답 모델을 확인할 수 있습니다. 이는 API 사용자에게 유용한 정보를 제공합니다.
  6. 실습 예시:
    • 위 코드는 GetPlant 엔드포인트에서 반환할 수 있는 상태 코드를 문서화하는 방법을 보여줍니다. StatusCodes 클래스를 사용하여 상태 코드를 더 명확하게 표현할 수 있습니다.
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
[HttpGet("id:int")]
public ActionResult<PlantDTO> GetPlant(int id)
{
    // 엔드포인트 로직...
}

이 방법을 통해 API 개발자는 엔드포인트에서 반환할 수 있는 다양한 상태 코드를 명확하게 문서화할 수 있으며, API 사용자는 Swagger 문서를 통해 이러한 정보를 쉽게 이해하고 사용할 수 있습니다.

프로젝트 리소스

https://github.com/kimdaewoong2022/MorePlants_WebAPI/tree/104d8f1cbb277149d0bde83aa403f9a778ca192e