SpringDocs의 @Schema를 사용하여 필드의 Description을 작성하려고 했으나 예상치 못한 이슈가 발생하였다.

나는 UserRequest 클래스에 대해서만 작성을 했는데, Response도 @Schema가 적용되어 버린 것이다.

왜 이런 일이 발생했을까?

Reuqest 객체

public class UserRequest {

	@Getter
	public static class Create {
		@Schema(description = "아이디", nullable = false, example = "artxlover")
		private String username;
		@Schema(description = "패스워드", nullable = false, example = "@artx1234@")
		private String password;
		@Schema(description = "이메일", nullable = false, example = "artx@gmail.com")
		private String email;
		@Schema(description = "이메일 수신 동의", nullable = false, example = "false")
		private Boolean isEmailYn;
		@Schema(description = "닉네임", nullable = false, example = "김작가")
		private String nickname;
		@Schema(description = "휴대폰 번호", nullable = false, example = "010-1234-5678")
		private String phoneNumber;
		@Schema(description = "주소", nullable = false, example = "서울특별시 은천로 1길")
		private String address;
		@Schema(description = "상세 주소", nullable = false, example = "101호")
		private String addressDetail;
		@Schema(description = "회원", nullable = false, example = "USER")
		private UserRole userRole;
	}

}

Response 객체

public class UserResponse {

	@Getter
	@Builder
	public static class Create {

		private UUID userId;
		private LocalDateTime createdAt;

		public static UserResponse.Create from(User user) {
			return Create.builder()
					.userId(user.getUserId())
					.createdAt(user.getCreatedAt())
					.build();
		}
	}
}

혹시 뭔가 이상한 점을 찾지 못하였는가? 바로 Inner Class의 이름이 같은 Create라는 것이다.

Spring Docs은 패키지와 상관 없이 Class 이름으로 구분하여 @Schema를 Swagger에 적용시킨다. 즉, Request객체의 Create 객체와 Response객체의 Create 객체가 같은 꼴이 되고, 먼저 찾아진 Request의 Create 객체를 기준으로 Response까지 @Schema가 적용이 되는 것이다

해결 방법

springdoc:
  use-fqn: true

application.yml에 위와 같이 설정을 해주면 해결할 수 있다. fqn은 fully qualifed name을 뜻하며 패키지명을 포함하여 Class를 찾기 위한 옵션이라고 보면 된다.```