Fix/73 swagger fixed dto

[zzmnxn]

🔗 Related Issue

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

📝 Description

무엇을(What), 왜(Why) 변경했는지 설명합니다.

기획 배경 및 비즈니스 문제

• 문제점: 공통 응답 포맷인 ApiResponseDto를 도입했으나, Swagger 문서상에서 모든 API의 data 필드가 특정 DTO(예: UserResponseDto)로 고정되어 표시되는 현상이 발생했습니다.
• 원인: ApiResponseDto에 설정된 @Schema(name = "ApiResponseDto")가 Springdoc의 제네릭 해석을 방해하여 단일 스키마로 병합되었으며, 커스텀 에러 응답 처리기가 고정된 스키마 이름을 참조하고 있었습니다.
• 목표: 제네릭 타입별로 정확한 응답 모델이 노출되도록 개선하고, 에러 응답 포맷(ApiResponseDto)을 표준화하여 문서의 정확도를 높입니다.

🛠 Changes

핵심 변경 사항을 요약합니다.

1. Swagger 응답 모델 최적화 (Generic Type 지원)

• ApiResponseDto 스키마 설정 수정: @Schema(name = "ApiResponseDto") 선언을 삭제했습니다.
  • 이유: 고정된 이름을 제거함으로써 Springdoc이 제네릭 타입(T)을 분석하여 ApiResponseDtoUserResponseDto와 같이 타입별로 고유한 스키마를 생성하도록 개선했습니다.
  • 효과: 모든 API의 응답 데이터가 특정 DTO로 고정되어 보이던 버그를 해결했습니다.

2. 에러 응답 전용 스키마(ApiResponseDtoVoid) 도입

• OpenApiConfig 스키마 명시적 등록: OpenApiCustomizer를 통해 ApiResponseDtoVoid 스키마를 공통 컴포넌트에 등록했습니다.
  • 에러 응답은 data 필드가 항상 null이므로 ApiResponseDto<Void> 형태를 표준으로 정의했습니다.
• SwaggerErrorCodeExampleCustomizer 수정 (68-73라인):
  • 에러 응답 스키마 참조를 #/components/schemas/ApiResponseDto → #/components/schemas/ApiResponseDtoVoid로 변경하여 성공 응답 모델과의 간섭을 차단했습니다.
  • CANNOT_ADD_DIARY_TO_PAST_TRIP 등 누락되었던 ErrorCode 매핑 로직을 추가했습니다.

3. 컨트롤러 응답 정의 규칙 통일

모든 컨트롤러 API 명세를 아래 표준 규칙에 맞춰 리팩토링했습니다.

구분	적용 내용	동작 원리
공통 응답	ResponseEntity<ApiResponseDto<T>> 적용	전사적 응답 포맷 일관성 유지
성공 응답	@ApiResponse 내 content 속성 제거	Springdoc이 메서드 반환 타입을 읽어 자동으로 스키마/예시 생성
에러 응답	content = @Content 속성 유지	SwaggerErrorCodeExampleCustomizer가 커스텀 에러 예시를 주입하도록 보장

✅ Test Checklist

변경 사항이 정상적으로 동작하는지 확인하기 위해 수행한 테스트 목록입니다.

• 각 컨트롤러(Diary, Country 등)의 성공 응답 data 필드에 해당 도메인 DTO 구조가 올바르게 표시되는가?

[sonarqubecloud]

Quality Gate failed

Failed conditions
0.0% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

[chwwwon]

openApi.getComponents()가 null일 경우 NPE가 발생할 수 있어 Components 존재 여부 검사/초기화 후 addSchemas 사용하도록 수정이 필요하다고 합니다

// 사용하는 버전에 따라 addProperties 사용 또는 Map으로 setProperties
        voidSchema.addProperties("code", codeSchema);
        voidSchema.addProperties("message", messageSchema);
        voidSchema.addProperties("data", dataSchema);

        openApi.getComponents().addSchemas("ApiResponseDtoVoid", voidSchema);

[chwwwon]

addProperties 메서드

Map<String, Schema> props = new LinkedHashMap<>();
props.put("code", codeSchema);
props.put("message", messageSchema);
props.put("data", dataSchema);
voidSchema.setProperties(props);

[chwwwon]

리뷰 확인해주세요!