Merge pull request #118 from onetime-with-members/feature/#115/add-an…

…notation

[style] : 주석을 추가하여 도메인 별 API들의 설명을 구체화한다

src/main/java/side/onetime/controller/EventController.java

@@ -18,7 +18,16 @@
 public class EventController {
     private final EventService eventService;
 
-    // 이벤트 생성 API
+    /**
+     * 이벤트 생성 API
+     *
+     * 이 API는 새로운 이벤트를 생성합니다. 인증된 유저와 익명 유저 모두 이벤트를 생성할 수 있으며,
+     * 인증된 유저의 경우 추가적인 정보가 저장됩니다.
+     *
+     * @param createEventRequest 생성할 이벤트에 대한 요청 데이터 (제목, 시작/종료 시간, 카테고리, 설문 범위 등)
+     * @param authorizationHeader 인증된 유저의 토큰 (선택 사항)
+     * @return 생성된 이벤트의 ID
+     */
     @PostMapping
     public ResponseEntity<ApiResponse<CreateEventResponse>> createEvent(
             @Valid @RequestBody CreateEventRequest createEventRequest,
@@ -34,19 +43,34 @@ public ResponseEntity<ApiResponse<CreateEventResponse>> createEvent(
         return ApiResponse.onSuccess(SuccessStatus._CREATED_EVENT, createEventResponse);
     }
 
-    // 이벤트 조회 API
+    /**
+     * 이벤트 조회 API
+     *
+     * 이 API는 특정 이벤트의 세부 정보를 조회합니다. 이벤트의 제목, 시간, 카테고리 등의 정보를 제공하며
+     * 인증된 유저일 경우 추가적인 정보가 포함될 수 있습니다.
+     *
+     * @param authorizationHeader 인증된 유저의 토큰 (선택 사항)
+     * @param eventId 조회할 이벤트의 ID
+     * @return 조회한 이벤트의 세부 정보
+     */
     @GetMapping("/{event_id}")
     public ResponseEntity<ApiResponse<GetEventResponse>> getEvent(
             @RequestHeader(value = "Authorization", required = false) String authorizationHeader,
             @PathVariable("event_id") String eventId) {
 
         GetEventResponse getEventResponse = eventService.getEvent(eventId, authorizationHeader);
 
-
         return ApiResponse.onSuccess(SuccessStatus._GET_EVENT, getEventResponse);
     }
 
-    // 참여자 조회 API
+    /**
+     * 참여자 조회 API
+     *
+     * 이 API는 특정 이벤트에 참여한 모든 참여자의 이름 목록을 조회합니다.
+     *
+     * @param eventId 참여자 목록을 조회할 이벤트의 ID
+     * @return 해당 이벤트에 참여한 참여자의 이름 목록
+     */
     @GetMapping("/{event_id}/participants")
     public ResponseEntity<ApiResponse<GetParticipantsResponse>> getParticipants(
             @PathVariable("event_id") String eventId) {
@@ -55,7 +79,14 @@ public ResponseEntity<ApiResponse<GetParticipantsResponse>> getParticipants(
         return ApiResponse.onSuccess(SuccessStatus._GET_PARTICIPANTS, getParticipantsResponse);
     }
 
-    // 가장 많이 되는 시간 조회 API
+    /**
+     * 가장 많이 되는 시간 조회 API
+     *
+     * 이 API는 특정 이벤트에서 가장 많이 가능한 시간대를 조회하여, 가능 인원과 해당 시간대 정보를 제공합니다.
+     *
+     * @param eventId 조회할 이벤트의 ID
+     * @return 가능 인원이 많은 시간대와 관련 세부 정보
+     */
     @GetMapping("/{event_id}/most")
     public ResponseEntity<ApiResponse<List<GetMostPossibleTime>>> getMostPossibleTime(
             @PathVariable("event_id") String eventId) {
@@ -64,7 +95,14 @@ public ResponseEntity<ApiResponse<List<GetMostPossibleTime>>> getMostPossibleTim
         return ApiResponse.onSuccess(SuccessStatus._GET_MOST_POSSIBLE_TIME, getMostPossibleTimes);
     }
 
-    // 유저 참여 이벤트 목록 조회 API
+    /**
+     * 유저 참여 이벤트 목록 조회 API
+     *
+     * 이 API는 인증된 유저가 참여한 모든 이벤트 목록을 조회합니다. 유저의 참여 상태, 이벤트 정보 등이 포함됩니다.
+     *
+     * @param authorizationHeader 인증된 유저의 토큰
+     * @return 유저가 참여한 이벤트 목록
+     */
     @GetMapping("/user/all")
     public ResponseEntity<ApiResponse<List<GetUserParticipatedEventsResponse>>> getUserParticipatedEvents(
             @RequestHeader("Authorization") String authorizationHeader) {
@@ -73,7 +111,15 @@ public ResponseEntity<ApiResponse<List<GetUserParticipatedEventsResponse>>> getU
         return ApiResponse.onSuccess(SuccessStatus._GET_USER_PARTICIPATED_EVENTS, getUserParticipatedEventsResponses);
     }
 
-    // 유저가 생성한 이벤트 삭제 API
+    /**
+     * 유저가 생성한 이벤트 삭제 API
+     *
+     * 이 API는 인증된 유저가 생성한 특정 이벤트를 삭제합니다.
+     *
+     * @param authorizationHeader 인증된 유저의 토큰
+     * @param eventId 삭제할 이벤트의 ID
+     * @return 삭제 성공 여부
+     */
     @DeleteMapping("/{event_id}")
     public ResponseEntity<ApiResponse<SuccessStatus>> removeUserCreatedEvent(
             @RequestHeader("Authorization") String authorizationHeader,
@@ -82,4 +128,4 @@ public ResponseEntity<ApiResponse<SuccessStatus>> removeUserCreatedEvent(
         eventService.removeUserCreatedEvent(authorizationHeader, eventId);
         return ApiResponse.onSuccess(SuccessStatus._REMOVE_USER_CREATED_EVENT);
     }
-}
+}

src/main/java/side/onetime/controller/FixedController.java

@@ -23,39 +23,68 @@ public class FixedController {
     private final FixedEventService fixedEventService;
     private final FixedScheduleService fixedScheduleService;
 
-    // 고정 이벤트 생성 및 고정 스케줄 등록 API
+    /**
+     * 고정 이벤트 생성 및 고정 스케줄 등록 API
+     *
+     * 이 API는 새로운 고정 이벤트를 생성하고 관련된 고정 스케줄을 등록합니다.
+     *
+     * @param authorizationHeader 인증된 유저의 토큰
+     * @param createFixedEventRequest 생성할 고정 이벤트에 대한 요청 데이터 (제목, 스케줄 목록 등)
+     * @return 생성 성공 여부를 나타내는 메시지
+     */
     @PostMapping
     public ResponseEntity<ApiResponse<Object>> createFixedEvent(
             @RequestHeader("Authorization") String authorizationHeader,
             @Valid @RequestBody CreateFixedEventRequest createFixedEventRequest) {
 
         fixedEventService.createFixedEvent(authorizationHeader, createFixedEventRequest);
-
         return ApiResponse.onSuccess(SuccessStatus._CREATED_FIXED_SCHEDULE);
     }
 
-    // 전체 고정 스케줄 조회 API
+    /**
+     * 전체 고정 스케줄 조회 API
+     *
+     * 이 API는 유저가 등록한 모든 고정 스케줄을 조회합니다.
+     *
+     * @param authorizationHeader 인증된 유저의 토큰
+     * @return 유저가 등록한 모든 고정 스케줄 목록
+     */
     @GetMapping
     public ResponseEntity<ApiResponse<List<FixedEventResponse>>> getAllFixedSchedules(
             @RequestHeader("Authorization") String authorizationHeader) {
 
         List<FixedEventResponse> fixedEventResponses = fixedScheduleService.getAllFixedSchedules(authorizationHeader);
-
         return ApiResponse.onSuccess(SuccessStatus._GET_ALL_FIXED_SCHEDULES, fixedEventResponses);
     }
 
-    // 특정 고정 스케줄 상세 조회 API
+    /**
+     * 특정 고정 스케줄 상세 조회 API
+     *
+     * 이 API는 특정 ID에 해당하는 고정 스케줄의 상세 정보를 조회합니다.
+     *
+     * @param authorizationHeader 인증된 유저의 토큰
+     * @param fixedEventId 조회할 고정 스케줄의 ID
+     * @return 조회된 고정 스케줄의 세부 정보
+     */
     @GetMapping("/{id}")
     public ResponseEntity<ApiResponse<FixedEventDetailResponse>> getFixedScheduleDetail(
             @RequestHeader("Authorization") String authorizationHeader,
             @PathVariable("id") Long fixedEventId) {
 
         FixedEventDetailResponse fixedEventDetailResponse = fixedScheduleService.getFixedScheduleDetail(authorizationHeader, fixedEventId);
-
         return ApiResponse.onSuccess(SuccessStatus._GET_FIXED_SCHEDULE_DETAIL, fixedEventDetailResponse);
     }
 
-    // 고정 이벤트 또는 스케줄 수정 API
+    /**
+     * 고정 이벤트 또는 스케줄 수정 API
+     *
+     * 이 API는 특정 고정 이벤트의 제목과 스케줄을 수정할 수 있습니다.
+     *
+     * @param authorizationHeader 인증된 유저의 토큰
+     * @param fixedEventId 수정할 고정 이벤트의 ID
+     * @param modifyFixedEventRequest 수정할 고정 이벤트의 제목 및 스케줄
+     * @return 수정 성공 여부를 나타내는 메시지
+     */
     @PatchMapping("/{id}")
     public ResponseEntity<ApiResponse<Object>> modifyFixedEvent(
             @RequestHeader("Authorization") String authorizationHeader,
@@ -72,25 +101,39 @@ public ResponseEntity<ApiResponse<Object>> modifyFixedEvent(
         return ApiResponse.onSuccess(SuccessStatus._MODIFY_FIXED_SCHEDULE);
     }
 
-    // 고정 이벤트 & 스케줄 삭제 API
+    /**
+     * 고정 이벤트 & 스케줄 삭제 API
+     *
+     * 이 API는 특정 ID에 해당하는 고정 이벤트와 관련된 스케줄을 삭제합니다.
+     *
+     * @param authorizationHeader 인증된 유저의 토큰
+     * @param fixedEventId 삭제할 고정 이벤트의 ID
+     * @return 삭제 성공 여부를 나타내는 메시지
+     */
     @DeleteMapping("/{id}")
     public ResponseEntity<ApiResponse<Object>> removeFixedEvent(
             @RequestHeader("Authorization") String authorizationHeader,
             @PathVariable("id") Long fixedEventId) {
 
         fixedEventService.removeFixedEvent(authorizationHeader, fixedEventId);
-
         return ApiResponse.onSuccess(SuccessStatus._REMOVE_FIXED_SCHEDULE);
     }
 
-    // 요일별 고정 이벤트 조회 API
+    /**
+     * 요일별 고정 이벤트 조회 API
+     *
+     * 이 API는 특정 요일에 해당하는 고정 이벤트 목록을 조회합니다.
+     *
+     * @param authorizationHeader 인증된 유저의 토큰
+     * @param day 조회할 요일 (예: 월, 화 등)
+     * @return 조회된 요일의 고정 이벤트 목록
+     */
     @GetMapping("by-day/{day}")
     public ResponseEntity<ApiResponse<List<FixedEventByDayResponse>>> getFixedEventByDay(
             @RequestHeader("Authorization") String authorizationHeader,
             @PathVariable("day") String day) {
 
         List<FixedEventByDayResponse> response = fixedEventService.getFixedEventByDay(authorizationHeader, day);
-
         return ApiResponse.onSuccess(SuccessStatus._GET_FIXED_EVENT_BY_DAY, response);
     }
-}
+}

src/main/java/side/onetime/controller/MemberController.java

@@ -23,7 +23,14 @@
 public class MemberController {
     private final MemberService memberService;
 
-    // 멤버 등록 API
+    /**
+     * 멤버 등록 API
+     *
+     * 이 API는 새로운 멤버를 등록합니다. 멤버가 속한 이벤트 ID와 이름, PIN, 스케줄 목록을 받습니다.
+     *
+     * @param registerMemberRequest 등록할 멤버 정보 (이벤트 ID, 이름, PIN, 스케줄 목록)
+     * @return 성공 여부와 등록된 멤버 정보 (멤버 ID, 이벤트 카테고리)
+     */
     @PostMapping("/action-register")
     public ResponseEntity<ApiResponse<RegisterMemberResponse>> registerMember(
             @Valid @RequestBody RegisterMemberRequest registerMemberRequest) {
@@ -32,7 +39,14 @@ public ResponseEntity<ApiResponse<RegisterMemberResponse>> registerMember(
         return ApiResponse.onSuccess(SuccessStatus._REGISTER_MEMBER, registerMemberResponse);
     }
 
-    // 멤버 로그인 API
+    /**
+     * 멤버 로그인 API
+     *
+     * 이 API는 멤버의 로그인 정보를 확인하고, 로그인에 성공한 경우 멤버의 정보를 반환합니다.
+     *
+     * @param loginMemberRequest 로그인할 멤버 정보 (이벤트 ID, 이름, PIN)
+     * @return 성공 여부와 로그인된 멤버 정보 (멤버 ID, 이벤트 카테고리)
+     */
     @PostMapping("/action-login")
     public ResponseEntity<ApiResponse<LoginMemberResponse>> loginMember(
             @Valid @RequestBody LoginMemberRequest loginMemberRequest) {
@@ -41,12 +55,19 @@ public ResponseEntity<ApiResponse<LoginMemberResponse>> loginMember(
         return ApiResponse.onSuccess(SuccessStatus._LOGIN_MEMBER, loginMemberResponse);
     }
 
-    // 이름 중복 확인 API
+    /**
+     * 이름 중복 확인 API
+     *
+     * 이 API는 특정 이벤트에서 지정한 이름이 중복되는지 확인합니다.
+     *
+     * @param isDuplicateRequest 중복 확인할 정보 (이벤트 ID, 확인할 이름)
+     * @return 성공 여부와 이름 사용 가능 여부 (isPossible 필드)
+     */
     @PostMapping("/name/action-check")
     public ResponseEntity<ApiResponse<IsDuplicateResponse>> isDuplicate(
             @Valid @RequestBody IsDuplicateRequest isDuplicateRequest) {
 
         IsDuplicateResponse isDuplicateResponse = memberService.isDuplicate(isDuplicateRequest);
         return ApiResponse.onSuccess(SuccessStatus._IS_POSSIBLE_NAME, isDuplicateResponse);
     }
-}
+}