[Trouble-shooting] 중첩 클래스명 중복으로 Swagger가 고장났다

스웨거로 사용자를 등록하려고 하는데, API 문서 내 DTO가 제대로 매핑이 되고 있지 않다는 걸 알게 됐다.

 

@Schema(description = "공지사항 요청 DTO")
class NoticeRequestDto {
    @Schema(description = "공지사항 등록 요청")
    class CREATE (
        @Schema(description = "제목")
        val title: String,

        @Schema(description = "내용")
        val content: String,

        @Schema(description = "작성자 이메일")
        val writerEmail: String
    )
}

@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
    )
}

• 이미지와 코드를 확인해 보면 스웨거가 다른 DTO를 매핑하고 있다는 걸 알 수 있다.
• 실제로 스웨거는 NoticeRequestDto$CREATE가 아닌 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는 보통 이런 형식으로 작성한다.
• 즉 중첩 클래스명이 모두 중복된다.
• 스웨거에서는 패키지 정보는 관리하지 않기 때문에 중첩 클래스명이 중복될 경우 매핑이 제대로 되지 않는다고 한다.

• 위 이미지처럼 DTO 클래스명을 바꾸면  정상적으로 매핑이 된다. 스키마명도 함께 바뀐 걸 확인할 수 있다.

 

그럼 중첩 클래스를 쓰더라도 클래스명이 중복되면 안 되나?

• 중첩 클래스명을 중복되지 않도록 모두 수정해야 하나?
• 결론적으로 아니다. 다음 두 가지 방법이 있다.
  • @Schema 어노테이션 선언 시 name을 지정해 주면 된다.
  • application.properties 파일에 설정을 추가하면 된다.

 
@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

• 클래스를 패키지로 구분하게끔 하는 설정이라고 한다.
• 감사하게도 다음 링크를 통해 알게 되었다.

swagger 사용시 패키지가 다른 동일 클래스를 구별하지 못하는 이슈

 

마치며

아무리 중첩 클래스라고 할지라도 클래스명이 겹치지 않는 게 좋을까?
단순 가독성이 좋아서 이렇게 작성해 왔는데, 어떻게 리팩토링 할지 조금 더 생각해 봐야겠다. 🤨

 

이미지 출처

스웨거 (소프트웨어) - 위키백과, 우리 모두의 백과사전