Swagger Request Example 추가하는 방법

[sangwonsheep]

개요

기존에 Request를 살펴보면, 기본 값으로 0, "string"이 세팅되어 있는 것을 볼 수 있다.
기본 값으로 세팅하지 않고, 우리가 직접 예제 값을 세팅할 수는 없을까?

이를 해결하기 위한 방법에는 총 2가지가 있다.

1. @Schema를 dto에 사용하여, 예제로 보여준다.
2. @ExampleObject를 사용하여, json 데이터를 그대로 예제로 보여준다.

---

1. @Schema

PickUpdateRequest에 @Schema를 사용한 코드

@Schema(description = "Pick 수정 요청")
public record PickUpdateRequest(
	@Schema(description = "Pick ID", example = "1")
	Long id,
	@Schema(description = "수정할 Pick 제목", example = "Spring Annotation")
	String title,
	@Schema(description = "수정할 Pick 설명(메모)", example = "Spring Annotation에 대한 픽")
	String memo,
	@Schema(description = "태그 id 리스트", example = "[1,2,3]")
	List<Long> tagIdList
) {
}

각 dto에 @Schema를 사용하여 상세 설명과 예제 데이터를 명시해주었다.

기존 값이 아닌 설정한 예시 값을 보여줄 수 있게 되었다.

또한, 상세 설명도 추가된 것을 확인할 수 있다.

---

2. @ExampleObject

PickApi의 updatePick method에 @RequestBody, @ExampleObject를 사용한 코드

@Operation(
	summary = "픽 수정",
	description = "픽을 수정합니다. (제목, 내용, 태그)"
)
@ApiResponses(value = {
	@ApiResponse(
		responseCode = "200",
		description = "픽 수정에 성공하였습니다."
	)
})
@RequestBody(
	content = @Content(
		examples = {
			@ExampleObject(
				name = "PickUpdateRequestExample",
				value = """
					{
						"id": 1,
						"title": "Updated Spring Annotation",
						 "memo": "Spring Annotation에 대한 새로운 설명",
						 "tagIdList": [
						    1,
						    2,
						    4
						 ]
					}
					"""
			)
		}
	)
)
ResponseEntity<PickResponse> updatePick(PickUpdateRequest pickUpdateRequest);

이 방식도 1번 방식과 동일한 결과를 보여주게 된다.


1번 방식과 다르게 각 변수에 대한 상세 정보는 나타나지 않는다.

dto에 사용? json 데이터 전체 사용?

• dto에 @Schema를 사용할 경우, 각 변수에 대한 상세 정보 및 예시 값을 설정할 수 있다.
• 반면에 json 데이터 전체를 사용하는 @ExampleObject를 사용할 경우, 각 변수에 대한 상세 정보를 설정할 수 없다.

@Schema를 사용하여 상세 정보까지 표현해주는 것이 더 좋은 방법이지 않을까 생각한다.
물론, json을 그대로 사용하고 싶다면, @ExampleObject를 사용하는 것도 좋은 방법이다.

추후 추가할 사항

null이 들어올 데이터, null이 들어오지 않을 데이터를 구분하는 것이 필요하다.
예를 들어, @NotNull과 같은 어노테이션을 붙여서 스웨거에 명확하게 설정해주어야 한다.

[Gyaak]

고생하셨습니다. 프로덕션 코드에 결국 swaager 관련 코드가 들어오게됬군요..
그래도 별도 api 명세 없이 예시코드까지 박을 수 있다는 점이 맘에 듭니다.
그리고 presentation layer와 application layer 사이의 dto에만 명세를 추가하면 되니 이정도는 괜찮을것같습니다.