[docs] Swagger 문서 상세화

[gihhyeon]

요약

OpenAPI 도입(#170) 후속 작업. 컨트롤러/엔드포인트 문서 어노테이션과 응답 DTO 예시를 추가해 Swagger 문서 가독성을 높인다.

What — 무엇을 바꿨나

• 컨트롤러 10개에 도메인별 @Tag, 엔드포인트별 @Operation 추가
• 인증 필요 엔드포인트에 401, 리소스 조회에 404 등 핵심 에러 응답 명시
• 응답 DTO(place, admin, lottery, user) 필드에 @Schema(example)로 예시 값 추가 (공용 DTO는 여러 API에 재사용)
• 에러 응답만 선언돼 성공 응답(200)이 문서에서 누락되던 문제 수정
• 문서 회귀 방지 스모크 테스트 추가(태그/요약 반영, 모든 엔드포인트 200 존재)

Why — 왜 필요한가

자동 생성된 문서에 태그·설명·예시가 없어 가독성이 떨어졌다. 도메인별 그룹화·요약·예시로 프론트가 API를 파악하기 쉽게 한다.

How — 어떻게 구현했나

• @Tag/@Operation은 정상 import, ApiResponse 래퍼와 이름이 겹치는 에러 응답 어노테이션만 FQN으로 표기해 충돌 회피
• 에러 응답 선언 시 springdoc가 기본 200을 대체하는 문제는 @ApiResponse(responseCode="200", useReturnTypeSchema=true)로 스키마와 함께 복구
• 예시는 컨트롤러가 아닌 DTO 필드 @Schema(example)에 두어 컨트롤러를 깔끔하게 유지하고 공용 DTO 예시를 재사용

체크리스트

• 불필요한 주석/코드 제거
• 테스트 추가/갱신 및 통과 (./gradlew test)
• 공개 계약 영향 확인 (엔드포인트·응답 형태 변경 없음)

관련 이슈

• close [docs] Swagger 문서 상세화 #171

기타 / 리뷰 포인트

• DTO 필드 @Schema 예시는 문서 표기용이며 실제 응답 값과 무관
• 성공/에러 응답 타입 분리(현재 ApiResponse envelope에 error 필드가 성공 스키마에도 노출)는 이번 범위 밖 → 별도 리팩터링 이슈로 다룰 예정