[Feat] folder api 추가, docs 추가

src/main/java/com/umc/timeto/block/controller/BlockController.java

@@ -1,11 +1,12 @@
 package com.umc.timeto.block.controller;
 
 import com.umc.timeto.block.dto.BlockAddDTO;
+import com.umc.timeto.block.dto.BlockResponseDTO;
+import com.umc.timeto.block.dto.BlockResponseDetailDTO;
 import com.umc.timeto.block.dto.BlockResponseNumDTO;
 import com.umc.timeto.block.service.BlockService;
 import com.umc.timeto.global.apiPayload.code.ResponseCode;
 import com.umc.timeto.global.apiPayload.dto.ResponseDTO;
-import io.swagger.v3.oas.annotations.Operation;
 import lombok.RequiredArgsConstructor;
 import org.springframework.format.annotation.DateTimeFormat;
 import org.springframework.http.ResponseEntity;
@@ -21,18 +22,17 @@
 @RestController
 @RequiredArgsConstructor
 @RequestMapping("/api/block")
-public class BlockController {
+public class BlockController implements BlockControllerDocs {
 
     private final BlockService blockService;
 
     private Long getMemberId(Authentication authentication) {
         return (Long) authentication.getPrincipal();
     }
 
-    @Operation(summary = "타임블럭 저장", description = "할 일 시작 시간을 받아서 블록을 저장합니다. 블록에는 일정 겹침 검사가 존재합니다." +
-            "(ex: 일정 1이 7:30~8:30 일떄, 일정2의 생성/이동은 8:30분 이상부터 가능)")
     @PatchMapping("/{todoId}")
-    public ResponseEntity<?> createBlock(
+    @Override
+    public ResponseEntity<ResponseDTO<BlockResponseDTO>> createBlock(
             @PathVariable Long todoId,
             @RequestBody BlockAddDTO req,
             Authentication authentication
@@ -44,9 +44,10 @@ public ResponseEntity<?> createBlock(
                 .body(new ResponseDTO<>(ResponseCode.SUCCESS_ADD_BLOCK, res));
     }
 
-    @Operation(summary = "날짜별 타임블럭 조회", description = "입력받은 날짜(yyyy-MM-DD)에 생성된 타임 블럭들을 조회합니다 블록 조회 기본(메인) 화면에 사용합니다. ")
+
     @GetMapping("/day")
-    public ResponseEntity<?> getBlockByDay(
+    @Override
+    public ResponseEntity<ResponseDTO<List<BlockResponseDetailDTO>>> getBlockByDay(
             // 기본 format: yyyy-MM-DD
             @RequestParam LocalDate date,
             Authentication authentication
@@ -58,9 +59,9 @@ public ResponseEntity<?> getBlockByDay(
                 .body(new ResponseDTO<>(ResponseCode.SUCCESS_GET_BLOCKLIST, res));
     }
 
-    @Operation(summary = "한달 날짜별 타임블럭 수",
-            description = "입력받은 날짜(YYYY-MM)에 생성된 타임 블럭 수를 조회합니다")
+
     @GetMapping("/month")
+    @Override
     public ResponseEntity<ResponseDTO<List<BlockResponseNumDTO>>> getBlockNumByMonth(
             @RequestParam
             @DateTimeFormat(pattern = "yyyy-MM")
@@ -75,9 +76,9 @@ public ResponseEntity<ResponseDTO<List<BlockResponseNumDTO>>> getBlockNumByMonth
                 .body(new ResponseDTO<>(ResponseCode.SUCCESS_GET_BLOCK_NUMBER, res));
     }
 
-    @Operation(summary = "블록 소요시간 변경",
-            description = "블록 소요시간 변경 시 사용합니다. 할 일 내부에서만 소요시간 변경이 가능하다면 사용하지 않아도 됩니다. ")
+
     @PatchMapping("/{blockId}/duration")
+    @Override
     public ResponseEntity<ResponseDTO<Void>> updateDuration(
             @PathVariable Long blockId,
             @RequestParam LocalTime duration,
@@ -96,10 +97,9 @@ public ResponseEntity<ResponseDTO<Void>> updateDuration(
     }
 
 
-    @Operation(summary = "블록 이동",
-            description = "블록을 드래그&드롭으로 이동했을 때 정보를 갱신합니다. 변경된 시작 시간을 입력으로 받습니다. " +
-                    "이동된 시간이 다른 일정과 겹칠 경우 갱신되지 않습니다. startAt format: yyyy-MM-dd'T'HH:mm")
+
     @PatchMapping("/{blockId}/move")
+    @Override
     public ResponseEntity<ResponseDTO<Void>> moveBlock(
             @PathVariable Long blockId,
             @RequestParam

src/main/java/com/umc/timeto/block/controller/BlockControllerDocs.java

@@ -0,0 +1,139 @@
+package com.umc.timeto.block.controller;
+
+import com.umc.timeto.block.dto.BlockAddDTO;
+import com.umc.timeto.block.dto.BlockResponseDTO;
+import com.umc.timeto.block.dto.BlockResponseDetailDTO;
+import com.umc.timeto.block.dto.BlockResponseNumDTO;
+import com.umc.timeto.global.apiPayload.dto.ResponseDTO;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.Schema;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import org.springframework.format.annotation.DateTimeFormat;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.core.Authentication;
+import org.springframework.web.bind.annotation.*;
+
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.time.LocalTime;
+import java.time.YearMonth;
+import java.util.List;
+
+public interface BlockControllerDocs {
+    @Operation(summary = "타임블럭 저장", description = "할 일 시작 시간을 받아서 블록을 저장합니다. 블록에는 일정 겹침 검사가 존재합니다." +
+            "(ex: 일정 1이 7:30~8:30 일떄, 일정2의 생성/이동은 8:30분 이상부터 가능)")
+    @ApiResponses({
+            @ApiResponse(
+                    responseCode = "201",
+                    description = "블록을 성공적으로 등록했습니다.",
+                    content = @Content(
+                            mediaType = "application/json"
+                    )
+            ),
+            @ApiResponse(
+                    responseCode = "400",
+                    description = "이미 해당 시간에 블록이 존재합니다.",
+                    content = @Content(schema = @Schema(hidden = true))
+            ),
+            @ApiResponse(
+                    responseCode = "404",
+                    description = "해당 아이디를 가진 할 일이 존재하지 않습니다.",
+                    content = @Content(schema = @Schema(hidden = true))
+            )
+    })
+    @PatchMapping("/{todoId}")
+    ResponseEntity<ResponseDTO<BlockResponseDTO>> createBlock(
+            @PathVariable Long todoId,
+            @RequestBody BlockAddDTO req,
+            Authentication authentication
+    );
+
+
+
+    @Operation(summary = "날짜별 타임블럭 조회", description = "입력받은 날짜(yyyy-MM-DD)에 생성된 타임 블럭들을 조회합니다 블록 조회 기본(메인) 화면에 사용합니다. ")
+    @ApiResponses({
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "블록 리스트를 성공적으로 불러왔습니다."
+            )
+    })
+    @GetMapping("/day")
+    ResponseEntity<ResponseDTO<List<BlockResponseDetailDTO>>> getBlockByDay(
+            // 기본 format: yyyy-MM-DD
+            @RequestParam LocalDate date,
+            Authentication authentication
+    );
+
+    @Operation(summary = "한달 날짜별 타임블럭 수",
+            description = "입력받은 날짜(YYYY-MM)에 생성된 타임 블럭 수를 조회합니다")
+    @ApiResponses({
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "블록 수를 성공적으로 불러왔습니다."
+            )
+    })
+    @GetMapping("/month")
+    ResponseEntity<ResponseDTO<List<BlockResponseNumDTO>>> getBlockNumByMonth(
+            @RequestParam
+            @DateTimeFormat(pattern = "yyyy-MM")
+            YearMonth yearMonth,
+            Authentication authentication
+    );
+
+    @Operation(summary = "블록 소요시간 변경",
+            description = "블록 소요시간 변경 시 사용합니다. 할 일 내부에서만 소요시간 변경이 가능하다면 사용하지 않아도 됩니다. ")
+    @ApiResponses({
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "블록을 성공적으로 업데이트했습니다"
+            ),
+            @ApiResponse(
+                    responseCode = "404",
+                    description = "해당 아이디를 가진 블록이 존재하지 않습니다.",
+                    content = @Content(schema = @Schema(hidden = true))
+            ),
+            @ApiResponse(
+                    responseCode = "400",
+                    description = "이미 해당 시간에 블록이 존재합니다."
+                    ,content = @Content(schema = @Schema(hidden = true))
+            )
+
+    })
+    @PatchMapping("/{blockId}/duration")
+    ResponseEntity<ResponseDTO<Void>> updateDuration(
+            @PathVariable Long blockId,
+            @RequestParam LocalTime duration,
+            Authentication authentication
+    );
+
+    @Operation(summary = "블록 이동",
+            description = "블록을 드래그&드롭으로 이동했을 때 정보를 갱신합니다. 변경된 시작 시간을 입력으로 받습니다. " +
+                    "이동된 시간이 다른 일정과 겹칠 경우 갱신되지 않습니다. startAt format: yyyy-MM-dd'T'HH:mm")
+    @ApiResponses({
+            @ApiResponse(
+                    responseCode = "200",
+                    description = "블록을 성공적으로 업데이트했습니다"
+            ),
+            @ApiResponse(
+                    responseCode = "400",
+                    description = "이미 해당 시간에 블록이 존재합니다."
+                    ,content = @Content(schema = @Schema(hidden = true))
+            ),
+            @ApiResponse(
+                    responseCode = "404",
+                    description = "해당 아이디를 가진 블록이 존재하지 않습니다."
+                    ,content = @Content(schema = @Schema(hidden = true))
+            )
+
+    })
+    @PatchMapping("/{blockId}/move")
+    ResponseEntity<ResponseDTO<Void>> moveBlock(
+            @PathVariable Long blockId,
+            @RequestParam
+            @DateTimeFormat(pattern = "yyyy-MM-dd'T'HH:mm")
+            LocalDateTime startAt,
+            Authentication authentication
+    );
+}

src/main/java/com/umc/timeto/block/dto/BlockAddDTO.java

@@ -1,7 +1,8 @@
 package com.umc.timeto.block.dto;
 
 
-import jakarta.validation.constraints.NotBlank;
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotNull;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Getter;
@@ -10,12 +11,20 @@
 
 import java.time.LocalDateTime;
 
+@Schema(description = "블록 생성 요청 DTO")
 @Getter
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
 public class BlockAddDTO {
-    @NotBlank(message = "startAt은 필수 입력 값입니다.")
+
+    @Schema(
+            description = "블록 시작 시간",
+            example = "2026-02-16T14:00",
+            type = "string",
+            pattern = "yyyy-MM-dd'T'HH:mm"
+    )
+    @NotNull(message = "startAt은 필수 입력 값입니다.")
     @DateTimeFormat(pattern = "yyyy-MM-dd'T'HH:mm")
     private LocalDateTime startAt;
 }

src/main/java/com/umc/timeto/block/dto/BlockResponseDTO.java

@@ -1,18 +1,34 @@
 package com.umc.timeto.block.dto;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
 
 import java.time.LocalDateTime;
 
+@Schema(description = "블록 생성/수정 응답 DTO")
 @Getter
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
 public class BlockResponseDTO {
+
+    @Schema(description = "블록 ID", example = "10")
     private Long blockId;
+
+    @Schema(description = "연결된 할 일 ID", example = "5")
     private Long todoId;
+
+    @Schema(
+            description = "블록 시작 시간",
+            example = "2026-02-16T14:00"
+    )
     private LocalDateTime startAt;
+
+    @Schema(
+            description = "블록 종료 시간",
+            example = "2026-02-16T16:00"
+    )
     private LocalDateTime endAt;
 }

src/main/java/com/umc/timeto/block/dto/BlockResponseDetailDTO.java

@@ -2,27 +2,45 @@
 
 import com.umc.timeto.todo.domain.enums.TodoPriority;
 import com.umc.timeto.todo.domain.enums.TodoState;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
 
 import java.time.LocalDateTime;
 
+@Schema(description = "블록 상세 조회 응답 DTO")
 @Getter
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
 public class BlockResponseDetailDTO {
+
+    @Schema(description = "블록 ID", example = "10")
     private Long blockId;
+
+    @Schema(description = "할 일 ID", example = "5")
     private Long todoId;
+
+    @Schema(description = "블록 시작 시간", example = "2026-02-16T14:00")
     private LocalDateTime startAt;
+
+    @Schema(description = "블록 종료 시간", example = "2026-02-16T16:00")
     private LocalDateTime endAt;
+
+    @Schema(description = "할 일 이름", example = "Spring 정렬 로직 구현")
     private String todoName;
+
+    @Schema(description = "할 일 우선순위", example = "HIGH")
     private TodoPriority priority;
+
+    @Schema(description = "할 일 상태", example = "progress")
     private TodoState state;
-    private String goalName;
-    private String color;
 
+    @Schema(description = "목표 이름", example = "백엔드 프로젝트")
+    private String goalName;
 
-}
+    @Schema(description = "목표 색상", example = "red")
+    private String color;
+}

src/main/java/com/umc/timeto/block/dto/BlockResponseNumDTO.java

@@ -1,18 +1,24 @@
 package com.umc.timeto.block.dto;
 
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.AllArgsConstructor;
 import lombok.Builder;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
 
 import java.time.LocalDate;
 
+@Schema(description = "날짜별 블록 개수 응답 DTO")
 @Getter
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
 public class BlockResponseNumDTO {
+
+    @Schema(description = "날짜", example = "2026-02-16")
     private LocalDate date;
+
+    @Schema(description = "해당 날짜의 블록 개수", example = "3")
     private Long count;
-}
+}