[BE] SISC1-201 [DOCS] Swagger 고도화 - API 응답 형식 정의

[ochanhyeok]

Summary by CodeRabbit

릴리스 노트

• Documentation
  • 출석 관리 API 문서화 개선. 출석 체크인, 세션별 출석 조회, 개인 출석 기록 조회 등 모든 API 엔드포인트에 상세한 설명과 예제를 추가하여 API 사용성을 향상시켰습니다.

[coderabbitai]

Walkthrough

출석 관련 컨트롤러 및 DTO 클래스에 Swagger/OpenAPI 주석을 추가했습니다. AttendanceController, AttendanceSessionController 클래스에 @tag 주석을 적용하고, 각 엔드포인트에 @operation 주석을 추가했습니다. 모든 요청/응답 DTO에 @Schema 주석을 적용하여 API 문서화 메타데이터를 확대했습니다. 메서드 시그니처나 기능 로직에는 변화가 없습니다.

Changes

그룹 / 파일	변경 요약
컨트롤러 backend/src/main/java/org/sejongisc/backend/attendance/controller/AttendanceController.java, backend/src/main/java/org/sejongisc/backend/attendance/controller/AttendanceSessionController.java	클래스 레벨 @tag 주석 추가; 4개 엔드포인트에 @operation 주석 추가 (체크인, 세션별 출석 조회, 개인 출석 기록 조회, 출석 상태 수정 등); Swagger 관련 import 추가; 각 메서드에 한국어 요약 및 상세 설명 포함
요청 DTO backend/src/main/java/org/sejongisc/backend/attendance/dto/AttendanceRequest.java, backend/src/main/java/org/sejongisc/backend/attendance/dto/AttendanceSessionRequest.java	클래스 레벨 @Schema 주석 추가; 모든 필드에 @Schema 주석 추가 (설명, 예시 포함); 기존 검증 주석(@notblank, @NotNull, @future, @min, @max 등) 유지; Schema import 추가
응답 DTO backend/src/main/java/org/sejongisc/backend/attendance/dto/AttendanceResponse.java, backend/src/main/java/org/sejongisc/backend/attendance/dto/AttendanceSessionResponse.java	클래스 레벨 @Schema 주석에 제목 및 설명 추가; 모든 공개 필드에 @Schema 주석 추가 (설명, 예시, 일부 구현 참조 포함); Schema import 추가; 런타임 로직 변화 없음

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 분

• 주목 영역:
  • 각 @Schema 및 @operation 주석의 한국어 설명과 예시가 정확한지 확인
  • 예시 값이 실제 데이터 타입과 일치하는지 검증 (예: 시간 형식, UUID, 좌표 범위)
  • enum 필드의 implementation 속성 참조 클래스 확인 (AttendanceStatus, SessionVisibility, SessionStatus)

Possibly related PRs

• [BE] SISC1 [FIX] Change @Controller to @RestController for Swagger #68: 동일한 컨트롤러 클래스(AttendanceController, AttendanceSessionController)의 스테레오타입을 @controller에서 @RestController로 변경
• [BE] SISC-162 [FEAT] Attendance 엔티티 User 연관관계 및 Repository, controller, DTO 구현, test 코드 작성 #38: 이번 PR이 Swagger/OpenAPI 주석을 추가하는 AttendanceController/AttendanceSessionController 및 출석 DTO 클래스들을 최초 도입
• [BE] SISC1-179 [TEST] attendance controller test 코드 구현 #58: AttendanceController 메서드를 수정 (Swagger 주석 추가 vs. 내부 사용자/UUID 처리 조정)

Suggested reviewers

• discipline24

Poem

🐰 문서를 수놓는 마법의 주석들,
출석 API는 더욱 명확해지고,
스웨거 주인공, 스키마 친구들과 함께,
개발자들의 길을 밝혀주네요.
✨ 우리 코드는 이제 자신감 있게 말한답니다!

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	제목 "[BE] SISC1-201 [DOCS] Swagger 고도화 - API 응답 형식 정의"는 changeset의 주요 변화를 명확하게 반영하고 있습니다. 실제로 AttendanceController, AttendanceSessionController, 그리고 여러 DTO 파일들에 Swagger/OpenAPI 주석(@tag, @operation, @Schema)을 추가하여 API 문서화를 강화하는 것이 이 PR의 핵심이며, 제목이 이를 정확하게 요약하고 있습니다. 제목은 구체적이고 명확하며, 모호한 표현(예: "misc updates")이 없고 파일 목록이나 불필요한 노이즈도 포함하지 않습니다.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch SISC1-201-BE-Swagger-고도화

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f1b582e and ded8071.

📒 Files selected for processing (6)

• backend/src/main/java/org/sejongisc/backend/attendance/controller/AttendanceController.java (6 hunks)
• backend/src/main/java/org/sejongisc/backend/attendance/controller/AttendanceSessionController.java (14 hunks)
• backend/src/main/java/org/sejongisc/backend/attendance/dto/AttendanceRequest.java (2 hunks)
• backend/src/main/java/org/sejongisc/backend/attendance/dto/AttendanceResponse.java (2 hunks)
• backend/src/main/java/org/sejongisc/backend/attendance/dto/AttendanceSessionRequest.java (2 hunks)
• backend/src/main/java/org/sejongisc/backend/attendance/dto/AttendanceSessionResponse.java (2 hunks)

🧰 Additional context used

🧬 Code graph analysis (2)

backend/src/main/java/org/sejongisc/backend/attendance/dto/AttendanceSessionRequest.java (1)

frontend/src/components/attendancemanage/CreateSessionForm.jsx (1)

• title (5-5)

backend/src/main/java/org/sejongisc/backend/attendance/dto/AttendanceRequest.java (1)

frontend/src/components/attendancemanage/CreateSessionForm.jsx (2)

• title (5-5)
• code (6-6)

🔇 Additional comments (6)

backend/src/main/java/org/sejongisc/backend/attendance/dto/AttendanceRequest.java (1)

3-68: LGTM! Swagger 문서화가 잘 구성되어 있습니다.

@Schema 주석이 각 필드에 명확하고 상세하게 추가되었습니다. 좌표 범위, 예제 값, 길이 제약 조건이 validation 어노테이션과 일관되게 설정되어 있어 API 문서의 품질이 크게 향상되었습니다.

backend/src/main/java/org/sejongisc/backend/attendance/dto/AttendanceSessionRequest.java (1)

3-106: LGTM! 세션 요청 DTO의 문서화가 우수합니다.

모든 필드에 대한 @Schema 주석이 상세하고 명확하게 작성되었습니다. 특히 enum 타입인 visibility 필드에 implementation = SessionVisibility.class를 지정하여 Swagger UI에서 가능한 값들을 확인할 수 있도록 한 점이 좋습니다.

backend/src/main/java/org/sejongisc/backend/attendance/controller/AttendanceSessionController.java (1)

3-279: LGTM! 컨트롤러 문서화가 체계적으로 완성되었습니다.

모든 엔드포인트에 @operation 주석이 추가되어 각 API의 목적과 동작이 명확하게 설명되어 있습니다. 관리자 전용 API에는 해당 내용이 명시되어 있고, 주의가 필요한 삭제 API에는 경고 이모지(⚠️)를 사용하여 주의사항을 강조한 점도 훌륭합니다.

backend/src/main/java/org/sejongisc/backend/attendance/dto/AttendanceResponse.java (1)

4-108: LGTM! 응답 DTO의 문서화가 완벽합니다.

모든 응답 필드에 대한 @Schema 주석이 명확하게 작성되었습니다. 날짜 형식의 예제가 @jsonformat 패턴과 일치하고, enum 타입인 attendanceStatus 필드에 implementation 속성을 지정하여 가능한 상태 값들을 문서화한 점이 우수합니다.

backend/src/main/java/org/sejongisc/backend/attendance/controller/AttendanceController.java (1)

3-128: LGTM! 출석 체크인 컨트롤러의 문서화가 명확합니다.

모든 엔드포인트에 @operation 주석이 추가되어 API의 목적과 동작이 잘 설명되어 있습니다. AttendanceSessionController와 구분되는 별도의 @tag를 사용하여 출석 체크인 관련 API와 세션 관리 API를 논리적으로 분리한 점이 좋습니다.

backend/src/main/java/org/sejongisc/backend/attendance/dto/AttendanceSessionResponse.java (1)

4-136: LGTM! 세션 응답 DTO의 문서화가 매우 상세합니다.

모든 필드에 대한 @Schema 주석이 체계적으로 작성되었습니다. 특히 remainingSeconds, checkInAvailable, participantCount 등 계산된 필드들에 대한 설명이 명확하여 API 사용자가 응답 구조를 쉽게 이해할 수 있습니다. 두 개의 enum 타입(visibility, status)에도 implementation 속성이 올바르게 지정되어 있습니다.

---

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 and usage tips.}

[discipline24]

고생하셨습니다