feature: Swagger 문서화 및 중복 문제 검증로직 추가 (#53)

Kimminu7 · web-flow · commit 30e740fa74b7 · 2025-06-12T12:42:16.000+09:00
* feat : 문제 생성시 중복체크 ( 제목 )

* refactor : 문제 생성시 중복체크 &lt;2&gt; ( 삭제된 문제인지 검증 추가 )

* feat : Swagger API 문서 작업

* feat : Swagger API 문서 작업 (2)
diff --git a/src/main/java/org/ezcode/codetest/application/problem/dto/request/ProblemCreateRequest.java b/src/main/java/org/ezcode/codetest/application/problem/dto/request/ProblemCreateRequest.java
@@ -6,30 +6,38 @@
 import org.ezcode.codetest.domain.problem.model.enums.Reference;
 import org.ezcode.codetest.domain.user.model.entity.User;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.NotNull;
 
 public record ProblemCreateRequest(
 
 	@NotNull(message = "카테고리를 설정해야 합니다.")
+	@Schema(description = "카테고리", example = "FOR_BEGINNER")
 	Category category,
 
 	@NotBlank(message = "문제 제목을 입력하세요.")
+	@Schema(description = "제목", example = "A+B")
 	String title,
 
 	@NotBlank(message = "문제 설명을 입력하세요.")
+	@Schema(description = "설명", example = "입력한 두수의 값을 더하고, 결과값을 출력하세요")
 	String description,
 
 	@NotNull(message = "난이도를 설정해야 합니다.")
+	@Schema(description = "난이도", example = "BRONZE")
 	Difficulty difficulty,
 
 	@NotNull(message = "메모리 제한을 설정해야 합니다.")
+	@Schema(description = "메모리 제한", example = "30000")
 	Long memoryLimit,
 
 	@NotNull(message = "시간 제한을 설정해야 합니다.")
+	@Schema(description = "시간 제한", example = "1000.0")
 	Double timeLimit,
 
 	@NotNull(message = "출처를 명시해야 합니다.")
+	@Schema(description = "출처", example = "ORIGINAL")
 	Reference reference
 
 ) {
diff --git a/src/main/java/org/ezcode/codetest/application/problem/dto/request/ProblemUpdateRequest.java b/src/main/java/org/ezcode/codetest/application/problem/dto/request/ProblemUpdateRequest.java
@@ -6,20 +6,29 @@
 import org.ezcode.codetest.domain.problem.model.enums.Reference;
 import org.ezcode.codetest.domain.user.model.entity.User;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 public record ProblemUpdateRequest(
 
+	@Schema(description = "카테고리", example = "FOR_BEGINNER")
 	Category category,
 
+	@Schema(description = "제목", example = "A+B")
 	String title,
 
+	@Schema(description = "카테고리", example = "입력한 두수의 값을 더하고, 결과값을 출력하세요")
 	String description,
 
+	@Schema(description = "난이도", example = "BRONZE")
 	Difficulty difficulty,
 
+	@Schema(description = "메모리 제한", example = "30000")
 	Long memoryLimit,
 
+	@Schema(description = "시간 제한", example = "1000.0")
 	Double timeLimit,
 
+	@Schema(description = "출처", example = "ORIGINAL")
 	Reference reference
 
 ) {
diff --git a/src/main/java/org/ezcode/codetest/application/problem/dto/request/TestcaseCreateRequest.java b/src/main/java/org/ezcode/codetest/application/problem/dto/request/TestcaseCreateRequest.java
@@ -3,10 +3,14 @@
 import org.ezcode.codetest.domain.problem.model.entity.Problem;
 import org.ezcode.codetest.domain.problem.model.entity.Testcase;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 public record TestcaseCreateRequest(
 
+	@Schema(description = "입력값", example = "2 3")
 	String input,
 
+	@Schema(description = "기댓값", example = "5")
 	String output
 
 ) {
diff --git a/src/main/java/org/ezcode/codetest/application/problem/dto/request/TestcaseUpdateRequest.java b/src/main/java/org/ezcode/codetest/application/problem/dto/request/TestcaseUpdateRequest.java
@@ -3,10 +3,14 @@
 import org.ezcode.codetest.domain.problem.model.entity.Problem;
 import org.ezcode.codetest.domain.problem.model.entity.Testcase;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
 public record TestcaseUpdateRequest(
 
+	@Schema(description = "입력값", example = "2 3")
 	String input,
 
+	@Schema(description = "기댓값", example = "5")
 	String output
 ) {
 
diff --git a/src/main/java/org/ezcode/codetest/application/problem/dto/response/ProblemDetailResponse.java b/src/main/java/org/ezcode/codetest/application/problem/dto/response/ProblemDetailResponse.java
@@ -6,33 +6,46 @@
 import org.ezcode.codetest.domain.problem.model.enums.Category;
 import org.ezcode.codetest.domain.problem.model.enums.Reference;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Builder;
 
 @Builder
 public record ProblemDetailResponse(
 
+	@Schema(description = "PK", example = "1")
 	Long id,
 
+	@Schema(description = "출제자", example = "홍길동")
 	String creator,
 
+	@Schema(description = "카테고리", example = "FOR_BEGINNER")
 	Category category,
 
+	@Schema(description = "제목", example = "A+B")
 	String title,
 
+	@Schema(description = "설명", example = "입력한 두수의 값을 더하고, 결과값을 출력하세요")
 	String description,
 
+	@Schema(description = "점수", example = "20")
 	int score,
 
+	@Schema(description = "난이도", example = "BRONZE")
 	String difficulty,
 
+	@Schema(description = "메모리 제한", example = "30000")
 	Long memoryLimit,
 
+	@Schema(description = "시간 제한", example = "1000.0")
 	Double timeLimit,
 
+	@Schema(description = "출처", example = "ORIGINAL")
 	Reference reference,
 
+	@Schema(description = "생성일", example = "2025-06-10 20:19:59.730028")
 	LocalDateTime createdAt,
 
+	@Schema(description = "수정일", example = "2025-06-11 08:12:43.506032")
 	LocalDateTime modifiedAt
 
 ) {
diff --git a/src/main/java/org/ezcode/codetest/application/problem/dto/response/ProblemResponse.java b/src/main/java/org/ezcode/codetest/application/problem/dto/response/ProblemResponse.java
@@ -4,23 +4,31 @@
 import org.ezcode.codetest.domain.problem.model.enums.Category;
 import org.ezcode.codetest.domain.problem.model.enums.Reference;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Builder;
 
 @Builder
 public record ProblemResponse(
 
+	@Schema(description = "PK", example = "1")
 	Long id,
 
+	@Schema(description = "출제자", example = "홍길동")
 	String creator,
 
+	@Schema(description = "카테고리", example = "FOR_BEGINNER")
 	Category category,
 
+	@Schema(description = "제목", example = "A+B")
 	String title,
 
+	@Schema(description = "점수", example = "20")
 	int score,
 
+	@Schema(description = "난이도", example = "BRONZE")
 	String difficulty,
 
+	@Schema(description = "출처", example = "ORIGINAL")
 	Reference reference
 
 ) {
diff --git a/src/main/java/org/ezcode/codetest/application/problem/dto/response/TestcaseResponse.java b/src/main/java/org/ezcode/codetest/application/problem/dto/response/TestcaseResponse.java
@@ -3,17 +3,22 @@
 import org.ezcode.codetest.domain.problem.model.entity.Problem;
 import org.ezcode.codetest.domain.problem.model.entity.Testcase;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Builder;
 
 @Builder
 public record TestcaseResponse(
 
+	@Schema(description = "PK", example = "1")
 	Long id,
 
+	@Schema(description = "FK", example = "1")
 	Long problemId,
 
+	@Schema(description = "입력값", example = "2 3")
 	String input,
 
+	@Schema(description = "기댓값", example = "5")
 	String output
 ) {
 
diff --git a/src/main/java/org/ezcode/codetest/domain/problem/exception/code/ProblemExceptionCode.java b/src/main/java/org/ezcode/codetest/domain/problem/exception/code/ProblemExceptionCode.java
@@ -11,7 +11,8 @@
 public enum ProblemExceptionCode implements ResponseCode {
 
 	PROBLEM_NOT_FOUND(false, HttpStatus.NOT_FOUND, "삭제 되었거나, 문제를 찾을수 없습니다."),
-	DIFFICULTY_NOT_FOUND(false, HttpStatus.NOT_FOUND, "삭제 되었거나, 난이도를 찾을수 없습니다.");
+	DIFFICULTY_NOT_FOUND(false, HttpStatus.NOT_FOUND, "삭제 되었거나, 난이도를 찾을수 없습니다."),
+	DUPLICATE_PROBLEM(false, HttpStatus.CONFLICT, "이미 존재하는 문제입니다.");
 
 	private final boolean success;
 
diff --git a/src/main/java/org/ezcode/codetest/domain/problem/repository/ProblemRepository.java b/src/main/java/org/ezcode/codetest/domain/problem/repository/ProblemRepository.java
@@ -20,4 +20,6 @@ public interface ProblemRepository {
 	void delete(Problem problem);
 
 	Optional<Problem> findProblemWithTestcasesById(Long problemId);
+
+	boolean existsByTitleAndIsDeletedIsFalse(String title);
 }
diff --git a/src/main/java/org/ezcode/codetest/domain/problem/service/ProblemDomainService.java b/src/main/java/org/ezcode/codetest/domain/problem/service/ProblemDomainService.java
@@ -24,6 +24,11 @@ public class ProblemDomainService {
 	//저장시 DB 뿐만 아니라 ElasticCache 에도 같이 저장합니다!
 	public Problem createProblem(Problem problem) {
 
+		// 중복된 문제 체크
+		if(problemRepository.existsByTitleAndIsDeletedIsFalse(problem.getTitle())) {
+			throw new ProblemException(ProblemExceptionCode.DUPLICATE_PROBLEM);
+		}
+
 		Problem savedProblem = problemRepository.save(problem);
 
 		searchRepository.save(ProblemSearchDocument.from(savedProblem));
diff --git a/src/main/java/org/ezcode/codetest/infrastructure/persistence/repository/problem/ProblemJpaRepository.java b/src/main/java/org/ezcode/codetest/infrastructure/persistence/repository/problem/ProblemJpaRepository.java
@@ -26,4 +26,6 @@ public interface ProblemJpaRepository extends JpaRepository<Problem, Long> {
 		where p.id = :problemId
 		""")
 	Optional<Problem> findProblemWithTestcasesById(@Param("problemId") Long problemId);
+
+	boolean existsByTitleAndIsDeletedIsFalse(String title);
 }
diff --git a/src/main/java/org/ezcode/codetest/infrastructure/persistence/repository/problem/ProblemRepositoryImpl.java b/src/main/java/org/ezcode/codetest/infrastructure/persistence/repository/problem/ProblemRepositoryImpl.java
@@ -48,4 +48,9 @@ public Optional<Problem> findProblemWithTestcasesById(Long problemId) {
 		return problemJpaRepository.findProblemWithTestcasesById(problemId);
 	}
 
+	@Override
+	public boolean existsByTitleAndIsDeletedIsFalse(String title) {
+		return problemJpaRepository.existsByTitleAndIsDeletedIsFalse(title);
+	}
+
 }
diff --git a/src/main/java/org/ezcode/codetest/presentation/problemmanagement/problem/ProblemAdminController.java b/src/main/java/org/ezcode/codetest/presentation/problemmanagement/problem/ProblemAdminController.java
@@ -16,17 +16,23 @@
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 
 @RestController
 @RequestMapping("/admin/problems")
 @RequiredArgsConstructor
+@Tag(name = "Problem(관리자)", description = "문제 API(관리자용)")
 public class ProblemAdminController {
 
 	private final ProblemService problemService;
 
 	@PostMapping
+	@Operation(summary = "문제 등록", description = "문제를 등록합니다.")
+	@ApiResponse(responseCode = "201", description = "문제 생성 성공")
 	public ResponseEntity<ProblemDetailResponse> createProblem(
 		@Valid @RequestBody ProblemCreateRequest request,
 		@AuthenticationPrincipal AuthUser user
@@ -38,6 +44,8 @@ public ResponseEntity<ProblemDetailResponse> createProblem(
 	}
 
 	@PutMapping("/{problemId}")
+	@Operation(summary = "문제 수정", description = "문제를 수정합니다.")
+	@ApiResponse(responseCode = "200", description = "문제 수정 성공")
 	public ResponseEntity<ProblemDetailResponse> modifyProblem(
 		@PathVariable Long problemId,
 		@Valid @RequestBody ProblemUpdateRequest request
@@ -49,6 +57,8 @@ public ResponseEntity<ProblemDetailResponse> modifyProblem(
 	}
 
 	@DeleteMapping("/{problemId}")
+	@Operation(summary = "문제 삭제", description = "문제를 삭제합니다.")
+	@ApiResponse(responseCode = "204", description = "문제 삭제 성공")
 	public ResponseEntity<Void> removeProblem(@PathVariable Long problemId) {
 
 		problemService.removeProblem(problemId);
diff --git a/src/main/java/org/ezcode/codetest/presentation/problemmanagement/problem/ProblemController.java b/src/main/java/org/ezcode/codetest/presentation/problemmanagement/problem/ProblemController.java
@@ -16,16 +16,22 @@
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import lombok.RequiredArgsConstructor;
 
 @RestController
 @RequestMapping("/problems")
 @RequiredArgsConstructor
+@Tag(name = "Problem", description = "문제 API")
 public class ProblemController {
 
 	private final ProblemService problemService;
 
 	@GetMapping
+	@Operation(summary = "문제 전체조회", description = "문제를 전체조회 합니다.")
+	@ApiResponse(responseCode = "200", description = "문제 전체 조회성공")
 	public ResponseEntity<Page<ProblemResponse>> getProblemsList(
 		@PageableDefault(sort = "createdAt", direction = Sort.Direction.DESC) Pageable pageable,
 		@RequestParam(required = false) Category category
@@ -37,6 +43,8 @@ public ResponseEntity<Page<ProblemResponse>> getProblemsList(
 	}
 
 	@GetMapping("/{problemId}")
+	@Operation(summary = "문제 상세조회", description = "문제를 상세조회 합니다.")
+	@ApiResponse(responseCode = "200", description = "문제 상세 조회성공")
 	public ResponseEntity<ProblemDetailResponse> getProblem(@PathVariable Long problemId) {
 
 		return ResponseEntity
diff --git a/src/main/java/org/ezcode/codetest/presentation/problemmanagement/testcase/TestcaseAdminController.java b/src/main/java/org/ezcode/codetest/presentation/problemmanagement/testcase/TestcaseAdminController.java
@@ -17,17 +17,23 @@
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RestController;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
 
 @RestController
 @RequestMapping("/admin/problems/{problemId}/testcases")
 @RequiredArgsConstructor
+@Tag(name = "Testcase(관리자)", description = "테스트 케이스 API(관리자용) ")
 public class TestcaseAdminController {
 
 	private final TestcaseService testcaseService;
 
 	@PostMapping
+	@Operation(summary = "테스트케이스 등록", description = "해당하는 문제에 테스트케이스를 등록합니다.")
+	@ApiResponse(responseCode = "201", description = "테스트케이스 생성 성공")
 	public ResponseEntity<TestcaseResponse> createTestcase(
 		@PathVariable Long problemId,
 		@Valid @RequestBody TestcaseCreateRequest request
@@ -39,6 +45,8 @@ public ResponseEntity<TestcaseResponse> createTestcase(
 	}
 
 	@GetMapping
+	@Operation(summary = "테스트케이스 조회", description = "해당하는 문제에 테스트케이스를 조회합니다.")
+	@ApiResponse(responseCode = "200", description = "테스트케이스 조회 성공")
 	public ResponseEntity<List<TestcaseResponse>> getTestcaseList(@PathVariable Long problemId) {
 
 		return ResponseEntity
@@ -47,6 +55,8 @@ public ResponseEntity<List<TestcaseResponse>> getTestcaseList(@PathVariable Long
 	}
 
 	@PutMapping("/{testcaseId}")
+	@Operation(summary = "테스트케이스 수정", description = "해당하는 문제에 테스트케이스를 수정합니다.")
+	@ApiResponse(responseCode = "200", description = "테스트케이스 수정 성공")
 	public ResponseEntity<TestcaseResponse> modifyTestcase(
 		@PathVariable Long problemId,
 		@PathVariable Long testcaseId,
@@ -59,6 +69,8 @@ public ResponseEntity<TestcaseResponse> modifyTestcase(
 	}
 
 	@DeleteMapping("/{testcaseId}")
+	@Operation(summary = "테스트케이스 삭제", description = "해당하는 문제에 테스트케이스를 삭제합니다.")
+	@ApiResponse(responseCode = "204", description = "테스트케이스 삭제 성공")
 	public ResponseEntity<Void> removeTestcase(
 		@PathVariable Long problemId,
 		@PathVariable Long testcaseId

Original file line number	Diff line number	Diff line change
`@@ -20,4 +20,6 @@ public interface ProblemRepository {`
`20`	`20`	`void delete(Problem problem);`
`21`	`21`
`22`	`22`	`Optional<Problem> findProblemWithTestcasesById(Long problemId);`
	`23`	`+`
	`24`	`+ boolean existsByTitleAndIsDeletedIsFalse(String title);`
`23`	`25`	`}`