[REFACTOR] Swagger 문서 형식 통일 (연주)

[on1yoneprivate]

📍 개요

연주 도메인의 Swagger 문서 형식을 통일하고, MVP에서 사용하지 않는 엔드포인트를 정리

⛓️‍💥 관련 이슈

• ♻️ Refactor - Swagger API 문서 형식 통일 #200

---

🛠️ 작업 내용

• 연주 API @tag name/description 형식 통일
• @operation summary에 API 접미사 적용 및 description 정리
• PathVariable에 @parameter(description, example) 추가
• 요청/응답 DTO에 @Schema(description, example) 보완
• MVP에서 사용하지 않는 연주 단건 조회 및 삭제 엔드포인트 제거
  • 추후 기능 확장 가능성을 고려하여 관련 Service 및 DTO는 유지
• 사용하지 않는 import 제거

---

🔥 리뷰 요청 사항

리뷰어가 중점적으로 확인해주었으면 하는 내용을 작성해주세요.

• 컨벤션 규칙에 맞게 작성이 됐는지

---

✅ 체크리스트

• 코드 컨벤션을 준수했습니다.
• 불필요한 코드 및 import를 제거했습니다.
• 예외 처리를 적용했습니다.
• 테스트를 완료했습니다.
• 관련 Issue를 연결했습니다.

---

📎 참고 사항

Summary by CodeRabbit

• 문서화

  • 연주 시작, MIDI 이벤트 저장, 녹음 업로드 및 분석 결과 API의 요청·응답 필드 설명과 예시가 보강되었습니다.
  • 연주 ID와 백킹트랙 등 주요 입력값의 Swagger 문서가 더 명확해졌습니다.
  • 연주 분석 마디 선택 정보 조회 API 설명이 간결하고 동작 중심으로 개선되었습니다.

• 변경 사항

  • 연주 상세 조회 및 연주 삭제 API가 제거되었습니다.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: a0998313-50e6-4182-9653-4ba4bfc4bd31

📥 Commits

Reviewing files that changed from the base of the PR and between dd92395 and 35fe136.

📒 Files selected for processing (9)

• src/main/java/com/mr/domain/playing/controller/PlayingController.java
• src/main/java/com/mr/domain/playing/dto/req/MidiEventSaveRequest.java
• src/main/java/com/mr/domain/playing/dto/req/PlayingStartRequest.java
• src/main/java/com/mr/domain/playing/dto/req/RecordingUploadUrlRequest.java
• src/main/java/com/mr/domain/playing/dto/res/AnalysisContextResponse.java
• src/main/java/com/mr/domain/playing/dto/res/MidiEventSaveResponse.java
• src/main/java/com/mr/domain/playing/dto/res/PlayingStartResponse.java
• src/main/java/com/mr/domain/playing/dto/res/RecordingUploadUrlResponse.java
• src/main/java/com/mr/domain/playing/service/PlayingService.java

💤 Files with no reviewable changes (1)

• src/main/java/com/mr/domain/playing/service/PlayingService.java

---

📝 Walkthrough

Walkthrough

Playing API의 Swagger 설명과 요청·응답 필드 메타데이터를 보강했습니다. 연주 상세 조회 및 삭제 엔드포인트를 제거하고, 분석 마디 선택 정보 조회 엔드포인트를 유지했습니다.

Changes

Playing API 변경

Layer / File(s)	Summary
Playing 요청·응답 스키마 문서화 src/main/java/com/mr/domain/playing/dto/req/*, src/main/java/com/mr/domain/playing/dto/res/*	요청·응답 필드에 Swagger 설명과 예시를 추가했습니다. 필드 타입, 검증 규칙, JSON 형식은 유지했습니다.
Playing 컨트롤러 엔드포인트 정리 src/main/java/com/mr/domain/playing/controller/PlayingController.java, src/main/java/com/mr/domain/playing/service/PlayingService.java	컨트롤러의 API 설명과 playingId 파라미터 문서를 수정했습니다. 연주 상세 조회·삭제 메서드를 제거하고 분석 마디 선택 정보 조회 API를 유지했습니다. 사용하지 않는 LocalDate import를 제거했습니다.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• Musereview/BE#72: 동일한 MIDI 이벤트 DTO와 PlayingController 엔드포인트를 다룹니다.
• Musereview/BE#89: 연주 상세 조회 및 삭제 API 추가와 직접 연결됩니다.
• Musereview/BE#161: AnalysisContextResponse와 분석 마디 선택 정보 조회 API를 도입했습니다.

Poem

연주 API에 설명이 피고
MIDI 필드마다 이름표를 달고
상세와 삭제 길은 닫혔네
분석의 마디는 남았네
Swagger 문서, 박자를 맞추네 🎵

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목은 연주 도메인의 Swagger 문서 형식 통일이라는 주요 변경을 명확하고 간결하게 설명합니다.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/#200-swagger-convention-playing

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[p1001q]

@tag(name = "연주", description = "연주 API") — 기존엔 "연주 세션 생성, 파일 업로드, MIDI 저장, 연주 기록 조회 및 삭제 API"였는데, 이번에 조회/삭제 엔드포인트를 지웠으니 그 설명을 유지했으면 오히려 더 부정확해졌을 겁니다. 짧게 바꾸신 게 맞는 선택으로 보입니다.

@parameter(description = "연주 ID", example = "128")가 playingId를 받는 세 개 엔드포인트(업로드 URL 발급/MIDI 저장/분석 컨텍스트 조회)에 전부 동일하게 붙어서 일관성 있습니다.

좋네요~ 승인해드렸습니다~

[rkdehdrbs7885-oss]

수고하셨습니다!