💥 Swagger 클래스명 중복

문제 상황

/* NoticeRequestDto$CREATE */
@Schema(description = "공지사항 요청 DTO")
class NoticeRequestDto {
	@Schema(description = "공지사항 등록 요청")
	class CREATE (
		@Schema(description = "제목")
		val title: String,
		
		@Schema(description = "내용")
		val content: String,
		
		@Schema(description = "작성자 이메일")
		val writerEmail: String
	)
}

/* InquiryRequestDto$CREATE */
@Schema(description = "문의 요청 DTO")
class InquiryRequestDto {
	@Schema(description = "문의 등록 요청")
	class CREATE (
		@Schema(description = "제목")
		val title: String,
		
		@Schema(description = "내용")
		val content: String,
		
		@Schema(description = "작성자 이메일")
		val writerEmail: String,
		
		@Schema(description = "작성자 전화번호")
		val writerPhoneNumber: String? = null
	)
}

• Swagger UI에서 공지사항 요청 DTO가 InquiryRequestDto$CREATE와 잘못 매핑 되었다.

문제 원인

NoticeRequestDto.class
├── CREATE.class
├── READ.class
├── UPDATE.class
└── DELETE.class

InquiryRequestDto.class
├── CREATE.class
├── READ.class
├── UPDATE.class
└── DELETE.class

UserRequestDto.class
├── CREATE.class
├── READ.class
├── UPDATE.class
└── DELETE.class

• 필자의 요청 DTO 구조인데, Swagger에서는 패키지 정보는 관리하지 않기 때문에 Nested Class 명이 중복될 경우 매핑이 제대로 되지 않는다고 한다.

해결 방법

✅ @Schema 선언 시 name 지정

@Schema(
	name = "createNoticeDto",
	description = "공지사항 등록 요청"
)
class CREATE (
	@Schema(description = "제목")
	val title: String,
	
	@Schema(description = "내용")
	val content: String,
	
	@Schema(description = "작성자 이메일")
	val writerEmail: String
)

• name 값은 다른 클래스와 겹치면 안 된다. 

✅ application.properties 설정

springdoc.use-fqn=true

• 클래스를 패키지로 구분하도록 하는 설정이라고 한다.

회고

• 아직은 Nested Class 기반의 요청 DTO 구조가 가독성 측면에서 좋다고 생각하고 있는데, 다른 방향도 생각해봐야겠다고 느꼈다.