[FIX] Swagger 응답 스키마가 특정 DTO(UserResponseDto)로 고정되는 현상

[zzmnxn]

1. 문제 상황

• 모든 컨트롤러의 공통 응답 포맷인 ApiResponseDto가 Swagger UI 상에서 특정 타입(예: UserResponseDto)으로만 표시되는 현상이 발생함.
• DiaryController 등 다른 컨트롤러에서도 성공 응답의 data 필드가 실제 반환 타입이 아닌 UserResponseDto로 고정되어 출력됨.

2. 원인 분석

• 스키마 이름 충돌: ApiResponseDto 클래스에 @Schema(name = "ApiResponseDto")가 선언되어 있어, Springdoc이 제네릭 타입별로 스키마를 생성하지 않고 하나의 고정된 이름(ApiResponseDto)으로 관리함.
• 스캔 순서 영향: 어플리케이션 기동 시 가장 먼저 스캔된 제네릭 타입(UserResponseDto)의 구조가 해당 스키마 이름의 기본 설계도로 등록됨.
• Customizer 간섭: SwaggerErrorCodeExampleCustomizer에서 에러 응답을 위해 #/components/schemas/ApiResponseDto를 강제 참조하고 있어, 스키마 고착화에 영향을 주고 있음.

3. 해결방법

• Option 1: ApiResponseDto의 Schema name 제거 (우선순위: 상)
  src/main/java/zim/tave/memory/global/common/ApiResponseDto.java 파일에서 @Schema(name = "ApiResponseDto") 속성을 삭제.

  • 삭제 시 Springdoc이 제네릭 인자(T)를 인식하여 ApiResponseDtoUserResponseDto, ApiResponseDtoDiaryResponseDto와 같이 고유한 스키마를 자동 생성함.

• Option 2: 컨트롤러 응답 타입 명시 (우선순위: 중)
  각 컨트롤러 메서드의 @apiresponse 어노테이션에 implementation을 직접 명시.

@ApiResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = DiaryResponseDto.class)))