[TASK] Swagger API 담당자 정보 추가

[IISweetHeartII]

Task Description

코드 리뷰 피드백에 따라 Swagger UI에서 API 담당자를 확인할 수 있도록 Controller에 담당자 정보를 추가합니다.

배경:

• 프론트엔드 팀이 Swagger만 보고 API 담당자를 확인하는 경우가 많음
• 현재는 담당자 정보가 없어 문의 시 누구에게 연락해야 할지 불명확
• 약 70개의 API 엔드포인트에 담당자 정보 추가 필요

선택한 방식: JavaDoc 주석 (권장)

별도의 Swagger extension을 사용하지 않고, 간단한 JavaDoc 주석으로 담당자를 표시합니다.

장점:

• ✅ 가장 간단하고 직관적
• ✅ IDE에서 바로 확인 가능
• ✅ 추가 설정 불필요
• ✅ 코드가 길어지지 않음
• ✅ JavaDoc 생성 시 자동 포함

Checklist

1단계: 패턴 정의

• JavaDoc 주석 형식 결정

/**
 * 결제 API
 * @author 홍길동
 * @team Backend
 * @contact hong@finders.com
 */
@Tag(name = "Payment", description = "결제 API")
@RestController
@RequestMapping("/payments")
public class PaymentController {
    // ...
}

2단계: Controller별 담당자 추가 (20개 파일)

• PaymentController (결제)
• PaymentWebhookController (결제 웹훅)
• PostController (커뮤니티)
• PhotoController (사진 조회)
• OwnerPhotoController (오너 사진)
• PhotoRestorationController (AI 복원)
• UserPhotoLabController (현상소 조회)
• OwnerPhotoLabController (오너 현상소)
• AdminPhotoLabController (관리자 현상소)
• ReservationController (예약)
• InquiryController (문의)
• OwnerInquiryController (오너 문의)
• AdminInquiryController (관리자 문의)
• MemberController (회원)
• MemberUserController (회원 유저)
• MemberAddressController (회원 주소)
• AuthController (인증)
• FileController (파일)
• DevMemberController (개발용)
• LocalMemberController (로컬 개발용)

3단계: 문서화

• CODE_STYLE.md에 JavaDoc 패턴 추가
• 예시 코드 작성

Related Domain

• Global/Infrastructure
• Documentation

Implementation Guide

적용 예시:

Before:

@Tag(name = "Payment", description = "결제 API")
@RestController
@RequiredArgsConstructor
@RequestMapping("/payments")
public class PaymentController {
    // ...
}

After:

/**
 * 결제 API
 * @author 홍길동
 * @team Backend
 * @contact hong@finders.com
 */
@Tag(name = "Payment", description = "결제 API")
@RestController
@RequiredArgsConstructor
@RequestMapping("/payments")
public class PaymentController {
    // ...
}

주의사항:

1. 실제 담당자 이름으로 변경: 예시의 "홍길동"을 실제 담당자로 교체
2. 일관된 형식 유지: 모든 Controller에서 동일한 JavaDoc 형식 사용
3. @team은 선택사항: 팀 구조가 명확하지 않으면 생략 가능
4. @contact는 선택사항: 이메일 공개가 부담스러우면 생략 가능

최소 형식 (권장):

/**
 * 결제 API
 * @author 홍길동
 */
@Tag(name = "Payment", description = "결제 API")

Additional Notes

대안으로 고려했던 방법들:

1. @tag의 extensions 사용

• 장점: Swagger 스펙에 포함됨
• 단점: 코드가 매우 길어짐 (70개 API에 적용 시 가독성 저하)

2. OpenAPI Configuration 전역 설정

• 장점: 한 곳에서 관리
• 단점: 도메인별 담당자가 다를 경우 유연성 부족

3. @operation의 extensions 사용

• 장점: 메서드별 담당자 지정 가능
• 단점: 중복 코드 과다 (70개 메서드 × 5줄 = 350줄 추가)

선택 이유:

• JavaDoc 방식이 가장 간단하고 실용적
• 코드 길이 증가 최소화 (Controller당 3-5줄만 추가)
• IDE 지원으로 개발자 경험 향상
• 기존 Java 표준 관행 준수

Related Issues / PRs

• Related to: 코드 리뷰 피드백 (2026-02-10)

Estimated Time

• 1-2 hours (20개 Controller 수정 + 문서 업데이트)