스웨거(Swagger) - 어노테이션 간단 정리

#0. 개요

• 원활한 프론트 - 백 소통을 위해, 개발하는 동시에 API 명세서를 만들어주는 swagger를 작성하는데에 소홀히하면 안 된다.
  • 백엔드 개발자는 코드를 직접 구현하여서, 스웨거를 통해 API 가 잘 호출되고, 결과가 이상적으로 리턴만 되는 것을 보면 스웨거도 잘 구현이 되었다고 생각을 하지만, 코드를 보지 못 하는 프론트엔드 개발자 입장에서는 각 API의 response / request 가 어떤 모양인지, 또한 각 Dto의 property 가 값의 유효 범위가 어떻게 되는지, 의미하는 바가 뭔지 알 수 있길 원한다.
  • 그렇기에 스웨거가 제공해주는 여러 어노테이션을 활용해 스웨거 문서를 직관적으로 꾸며보자

#1. 어노테이션 종류

1. @Operation

• 각 API에 대한 설명을 스웨거에 띄워주는 용도. 보통 summary 와 description 을 통해서 해당 API 가 어떤 역할인 지 명시해준다.
• @Operation(description = "메뉴를 조회하기 위한 API", summary = "메뉴 조회")

2. @RequestBody

• Put / Post method API의 Request Body 를 설명해주는 어노테이션
  • @ExampleObject와 함께 많이 쓰인다.
• controller 메서드 파라미터 위에 어노테이션을 달아주면 된다.

@RequestBody(content = @Content(
	examples = {
		@ExampleObject(name = "예시", ref = "#/components/examples/menu.put")
	}))

• 해당 어노테이션은 동명이인이 존재한다.
  • 스웨거 어노테이션:
    • io.swagger.v3.oas.annotations.parameters
  • 스프링 제공:
    • org.springframework.web.bind.annotation
  • 보통 두 개를 같이 많이 써서, 한 쪽은 앞 패키지 명칭까지 풀로 붙여줘야한다.

3. @ApiResponse

• 보통 Get method API 의 Response 가 어떻게 오는 지 설명해주는 어노테이션
  • response의 스키마를 설명하기 위해 @Content / @Schema 어노테이션과 함께 많이 쓰인다.
    • @Schema 어노테이션은 Dto 정의시 각 property 위에 이름과 설명을 붙일 때 사용하여, ApiResponse 어노테이션을 통해 Dto의 설명을 같이 반환할 수 있다.

  //결과가 단일 dto 객체인 경우
  	@ApiResponse(responseCode = "200", description = "성공",
  		content = @Content(schema = @Schema(implementation = Dto.class)))
  
  //결과가 array 인 경우
  	@ApiResponse(responseCode = "200", description = "성공",
  		content = @Content(array = @ArraySchema(schema = @Schema(implementation = Dto.class))))