[#9] Task CRUD API 스펙 정의 및 생성

README.md

@@ -1 +1,8 @@
-# task-buddy
+# task-buddy
+
+
+## Git
+### Work Flow
+1. Issue 발생하여 TODO 등록
+2. feature 브랜치 생성 (브랜치명: `feature/{Issue 번호}-{작업타이틀}`)
+3. PR 제출 (제목: `[{issue 번호}] {작업 주제}`)

api/build.gradle

@@ -2,6 +2,8 @@ plugins {
     id 'java'
     id 'org.springframework.boot' version '3.3.2'
     id 'io.spring.dependency-management' version '1.1.6'
+    id "io.freefair.lombok" version "8.7.1"
+    id "org.asciidoctor.jvm.convert" version "3.3.2"
 }
 
 java {
@@ -15,12 +17,34 @@ repositories {
     mavenCentral()
 }
 
+configurations {
+    asciidoctorExt
+}
+
 dependencies {
     implementation project(':core')
     implementation 'org.springframework.boot:spring-boot-starter-web'
+    asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor'
+    implementation 'com.fasterxml.jackson.datatype:jackson-datatype-jsr310'
     testImplementation 'org.springframework.boot:spring-boot-starter-test'
+    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
+}
+
+ext {
+    snippetsDir = file('build/generated-snippets')
 }
 
 test {
     useJUnitPlatform()
+    outputs.dir snippetsDir
+}
+
+asciidoctor {
+    inputs.dir snippetsDir
+    configurations 'asciidoctorExt'
+    dependsOn test
+}
+
+bootJar {
+    dependsOn asciidoctor
 }

api/src/docs/asciidoc/index.adoc

@@ -0,0 +1,10 @@
+= Api Document
+:doctype: book
+:icons: font
+:source-highlighter: highlightjs
+:toc: left
+:toclevels: 1
+:sectlinks:
+:docinfo: shared-head
+
+include::/{docfile}/../task.adoc[]

api/src/docs/asciidoc/task.adoc

@@ -0,0 +1,58 @@
+== 1. Task
+
+[[resources-tasks-get]]
+=== 1) Task 조회
+
+`GET` 요청을 사용해서 기존 Task 하나를 조회할 수 있다.
+
+==== 성공 응답
+operation::get-a-task-with-id/success[snippets='request-headers,path-parameters,http-request,response-headers,response-fields,http-response']
+
+==== Task가 존재하지 않을 경우
+operation::get-a-task-with-id/fail/does-not-exist[snippets='http-request,http-response']
+
+==== 잘못된 형식의 ID로 요청한 경우
+operation::get-a-task-with-id/fail/negative-id-value[snippets='http-request,http-response']
+
+
+[[resources-tasks-create]]
+=== 2) Task 생성
+
+`POST` 요청을 사용해서 새 Task를 만들 수 있다.
+
+==== 성공 응답
+operation::create-a-task/success[snippets='request-headers,request-fields,http-request,response-headers,response-fields,http-response']
+
+==== Request 조건에 만족하지 않을 경우
+operation::create-a-task/fail/invalid-request-data[snippets='http-request,http-response']
+
+[[resources-tasks-update]]
+=== 3) Task 수정
+
+`PATCH` 요청을 사용해서 기존 Task를 수정할 수 있다.
+
+==== 성공 응답
+operation::update-a-task/success[snippets='request-headers,path-parameters,request-fields,http-request,response-headers,response-fields,http-response']
+
+==== 잘못된 형식의 ID로 요청한 경우
+operation::update-a-task/fail/negative-id-value[snippets='http-request,http-response']
+
+==== Request 조건에 만족하지 않을 경우
+operation::update-a-task/fail/invalid-request-data[snippets='http-request,http-response']
+
+==== Task가 존재하지 않을 경우
+operation::update-a-task/fail/does-not-exist[snippets='http-request,http-response']
+
+[[resources-tasks-remove]]
+=== 4) Task 삭제
+
+`DELETE` 요청을 사용해서 기존 Task를 수정할 수 있다.
+
+==== 성공 응답
+operation::remove-a-task/success[snippets='request-headers,path-parameters,http-request,response-headers,response-fields,http-response']
+
+==== 잘못된 형식의 ID로 요청한 경우
+operation::remove-a-task/fail/negative-id-value[snippets='http-request,http-response']
+
+==== Task가 존재하지 않을 경우
+operation::remove-a-task/fail/does-not-exist[snippets='http-request,http-response']

api/src/main/java/com/taskbuddy/api/controller/ApiControllerAdvice.java

@@ -0,0 +1,26 @@
+package com.taskbuddy.api.controller;
+
+import com.taskbuddy.api.controller.response.ApiResponse;
+import com.taskbuddy.api.controller.response.ErrorDetail;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+
+@RestControllerAdvice
+public class ApiControllerAdvice {
+
+    @ExceptionHandler(IllegalStateException.class)
+    public ResponseEntity<ApiResponse<?>> handleIllegalStateException(IllegalStateException exception) {
+        return ResponseEntity
+                .status(HttpStatus.BAD_REQUEST)
+                .body(ApiResponse.fail(new ErrorDetail("INVALID_PARAMETER_STATE", exception.getMessage())));
+    }
+
+    @ExceptionHandler(IllegalArgumentException.class)
+    public ResponseEntity<ApiResponse<?>> handleIllegalArgumentException(IllegalArgumentException exception) {
+        return ResponseEntity
+                .status(HttpStatus.BAD_REQUEST)
+                .body(ApiResponse.fail(new ErrorDetail("INVALID_PARAMETER_STATE", exception.getMessage())));
+    }
+}

api/src/main/java/com/taskbuddy/api/common/HealthController.java → api/src/main/java/com/taskbuddy/api/controller/HealthController.java

@@ -1,4 +1,4 @@
-package com.taskbuddy.api.common;
+package com.taskbuddy.api.controller;
 
 import org.springframework.http.HttpStatus;
 import org.springframework.web.bind.annotation.GetMapping;
@@ -10,5 +10,8 @@ public class HealthController {
 
     @ResponseStatus(code = HttpStatus.OK)
     @GetMapping("/health-check")
-    public void healthCheck() {}
+    public void healthCheck() {
+
+    }
+
 }

api/src/main/java/com/taskbuddy/api/controller/TaskController.java

@@ -0,0 +1,77 @@
+package com.taskbuddy.api.controller;
+
+import com.taskbuddy.api.controller.request.TaskCreateRequest;
+import com.taskbuddy.api.controller.request.TaskUpdateRequest;
+import com.taskbuddy.api.controller.response.ApiResponse;
+import com.taskbuddy.api.controller.response.task.TaskResponse;
+import com.taskbuddy.api.controller.response.task.TimeFrame;
+import org.springframework.http.ResponseEntity;
+import org.springframework.util.Assert;
+import org.springframework.web.bind.annotation.*;
+
+import java.net.URI;
+import java.time.LocalDateTime;
+
+@RequestMapping("/v1/tasks")
+@RestController
+public class TaskController {
+    @GetMapping("/{id}")
+    ResponseEntity<ApiResponse<TaskResponse>> getTask(@PathVariable("id") Long id) {
+        Assert.state(id >= 0, "The id value must be positive.");
+
+        // FIXME 서비스 로직 구현하면 제거하기
+        if (id == 0) {
+            throw new IllegalArgumentException("The given task with id does not exist.");
+        }
+
+        //Dummy
+        TaskResponse response = new TaskResponse(
+                1L
+                , "알고리즘 문제 풀기"
+                , "백준1902..."
+                , false
+                , new TimeFrame(
+                        LocalDateTime.of(2024, 8, 1, 0, 0, 0)
+                        , LocalDateTime.of(2024, 8, 31, 23, 59, 59)));
+
+        return ResponseEntity
+                .ok(ApiResponse.success(response));
+    }
+
+    @PostMapping
+    ResponseEntity<ApiResponse<?>> createTask(@RequestBody TaskCreateRequest request) {
+        //Dummy
+        final long createdTaskId = 1L;
+
+        return ResponseEntity
+                .created(URI.create("localhost:8080/v1/tasks/" + createdTaskId))
+                .body(ApiResponse.success());
+    }
+
+    @PatchMapping("/{id}")
+    ResponseEntity<ApiResponse<?>> updateTask(@PathVariable("id") Long id, @RequestBody TaskUpdateRequest request) {
+        Assert.state(id >= 0, "The id value must be positive.");
+
+        // FIXME 서비스 로직 구현하면 제거하기
+        if (id == 0) {
+            throw new IllegalArgumentException("The given task with id does not exist.");
+        }
+
+        return ResponseEntity
+                .ok(ApiResponse.success());
+    }
+
+    @DeleteMapping("/{id}")
+    ResponseEntity<ApiResponse<?>> removeTask(@PathVariable("id") Long id) {
+        Assert.state(id >= 0, "The id value must be positive.");
+
+        // FIXME 서비스 로직 구현하면 제거하기
+        if (id == 0) {
+            throw new IllegalArgumentException("The given task with id does not exist.");
+        }
+
+        return ResponseEntity
+                .ok(ApiResponse.success());
+    }
+
+}

api/src/main/java/com/taskbuddy/api/controller/request/TaskCreateRequest.java

@@ -0,0 +1,16 @@
+package com.taskbuddy.api.controller.request;
+
+import com.taskbuddy.api.controller.response.task.TimeFrame;
+import org.springframework.util.Assert;
+
+public record TaskCreateRequest(
+        String title,
+        String description,
+        TimeFrame timeFrame
+) {
+    public TaskCreateRequest {
+        Assert.state(title != null && !title.isBlank(), "The title of task must not be blank.");
+        Assert.state(description == null || description.length() <= 500, "The description length must be equal or less than 500");
+        Assert.notNull(timeFrame, "The timeFrame must not be null.");
+    }
+}

api/src/main/java/com/taskbuddy/api/controller/request/TaskUpdateRequest.java

@@ -0,0 +1,16 @@
+package com.taskbuddy.api.controller.request;
+
+import com.taskbuddy.api.controller.response.task.TimeFrame;
+import org.springframework.util.Assert;
+
+public record TaskUpdateRequest(
+        String title,
+        String description,
+        TimeFrame timeFrame
+) {
+    public TaskUpdateRequest {
+        Assert.state(title != null && !title.isBlank(), "The title of task must not be blank.");
+        Assert.state(description == null || description.length() <= 500, "The description length must be equal or less than 500");
+        Assert.notNull(timeFrame, "The timeFrame must not be null.");
+    }
+}

api/src/main/java/com/taskbuddy/api/controller/response/ApiResponse.java

@@ -0,0 +1,33 @@
+package com.taskbuddy.api.controller.response;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import lombok.Getter;
+import org.springframework.util.Assert;
+
+@JsonInclude(JsonInclude.Include.NON_NULL)
+@Getter
+public class ApiResponse<D> {
+    private final ResultStatus status;
+    private final D data;
+    private final ErrorDetail error;
+
+    private ApiResponse(ResultStatus status, D data, ErrorDetail error) {
+        this.status = status;
+        this.data = data;
+        this.error = error;
+    }
+
+    public static <D> ApiResponse<D> success(D data) {
+        return new ApiResponse<>(ResultStatus.SUCCESS, data, null);
+    }
+
+    public static ApiResponse<?> success() {
+        return new ApiResponse<>(ResultStatus.SUCCESS, null, null);
+    }
+
+    public static ApiResponse<?> fail(ErrorDetail error) {
+        Assert.notNull(error, "The error argument must not be null.");
+
+        return new ApiResponse<>(ResultStatus.FAIL, null, error);
+    }
+}

api/src/main/java/com/taskbuddy/api/controller/response/ErrorDetail.java

@@ -0,0 +1,4 @@
+package com.taskbuddy.api.controller.response;
+
+public record ErrorDetail(String code, String message) {
+}

api/src/main/java/com/taskbuddy/api/controller/response/ResultStatus.java

@@ -0,0 +1,6 @@
+package com.taskbuddy.api.controller.response;
+
+public enum ResultStatus {
+    SUCCESS,
+    FAIL,
+}

api/src/main/java/com/taskbuddy/api/controller/response/task/TaskResponse.java

@@ -0,0 +1,9 @@
+package com.taskbuddy.api.controller.response.task;
+
+public record TaskResponse (
+        Long id,
+        String title,
+        String description,
+        Boolean isDone,
+        TimeFrame timeFrame
+) {}

api/src/main/java/com/taskbuddy/api/controller/response/task/TimeFrame.java

@@ -0,0 +1,15 @@
+package com.taskbuddy.api.controller.response.task;
+
+import org.springframework.util.Assert;
+
+import java.time.LocalDateTime;
+
+public record TimeFrame(
+        LocalDateTime startDateTime,
+        LocalDateTime endDateTime) {
+    public TimeFrame {
+        Assert.notNull(startDateTime, "The startDateTime must not be null.");
+        Assert.notNull(endDateTime, "The endDateTime must not be null.");
+        Assert.isTrue(endDateTime.isAfter(startDateTime), "The endDateTime must be after than the startDateTime.");
+    }
+}