Docs: KycManageApi 문서화

gaseng · Nov 14, 2023 · 9668b49 · 9668b49
1 parent 264a29d
commit 9668b49
Show file tree

Hide file tree

Showing 3 changed files with 48 additions and 6 deletions.
diff --git a/src/main/java/com/gaseng/kyc/controller/KycManageApiController.java b/src/main/java/com/gaseng/kyc/controller/KycManageApiController.java
@@ -7,7 +7,10 @@
 import com.gaseng.kyc.service.KycManageService;
 import io.swagger.annotations.Api;
 import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.parameters.RequestBody;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import lombok.RequiredArgsConstructor;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.web.bind.annotation.*;
@@ -24,29 +27,58 @@ public class KycManageApiController {
 
 	@PreAuthorize("hasRole('ADMIN')")
 	@Operation(summary = "kyc 요청 조회", description = "kyc 요청서를 조회합니다.")
+	@ApiResponses(value = {
+			@ApiResponse(responseCode = "200", description = "요청에 성공했습니다."),
+			@ApiResponse(responseCode = "404", description = "KYC 요청을 찾을 수 없습니다."),
+			@ApiResponse(responseCode = "500", description = "서버와의 연결에 실패했습니다.")
+	})
 	@GetMapping("")
-	public BaseResponse<KycRequireResponse> get(@RequestParam Long kycrId) {
+	public BaseResponse<KycRequireResponse> get(
+			@Parameter(description = "kyc require id", required = true, example = "1")
+			@RequestParam Long kycrId
+	) {
 		return new BaseResponse<>(kycManageService.get(kycrId));
 	}
 
 	@PreAuthorize("hasRole('ADMIN')")
-	@Operation(summary = "kyc 요청 전체 조회", description = "kyc 요청서를 조회합니다.")
+	@Operation(summary = "kyc 요청 전체 조회", description = "kyc 요청서 목록을 조회합니다.")
+	@ApiResponses(value = {
+			@ApiResponse(responseCode = "200", description = "요청에 성공했습니다."),
+			@ApiResponse(responseCode = "500", description = "서버와의 연결에 실패했습니다.")
+	})
 	@GetMapping("/all")
 	public BaseResponse<List<KycRequireSummaryResponse>> getAll() {
 		return new BaseResponse<>(kycManageService.getAll());
 	}
 
 	@PreAuthorize("hasRole('ADMIN')")
 	@Operation(summary = "kyc 저장", description = "kyc를 저장합니다.")
+	@ApiResponses(value = {
+			@ApiResponse(responseCode = "200", description = "요청에 성공했습니다."),
+			@ApiResponse(responseCode = "404", description = "KYC 요청을 찾을 수 없습니다. / 비활성화된 KYC 요청입니다."),
+			@ApiResponse(responseCode = "500", description = "서버와의 연결에 실패했습니다.")
+	})
 	@PostMapping("")
-	public BaseResponse<Long> save(@RequestParam Long kycrId, @RequestBody @Valid KycSaveRequest request) throws Exception {
+	public BaseResponse<Long> save(
+			@Parameter(description = "kyc require id", required = true, example = "1")
+			@RequestParam Long kycrId,
+			@RequestBody @Valid KycSaveRequest request
+	) throws Exception {
 		return new BaseResponse<>(kycManageService.save(kycrId, request));
 	}
 
 	@PreAuthorize("hasRole('ADMIN')")
 	@Operation(summary = "범죄 이력 조회", description = "kyc 인증을 요청한 사용자의 범죄 이력을 조회합니다.")
+	@ApiResponses(value = {
+			@ApiResponse(responseCode = "200", description = "요청에 성공했습니다."),
+			@ApiResponse(responseCode = "404", description = "KYC 요청을 찾을 수 없습니다. / 일치하는 회원이 없습니다."),
+			@ApiResponse(responseCode = "500", description = "서버와의 연결에 실패했습니다.")
+	})
 	@GetMapping("/criminal-records/{kycrId}")
-	public BaseResponse<String> getCriminalRecord(@PathVariable Long kycrId) {
+	public BaseResponse<String> getCriminalRecord(
+			@Parameter(description = "kyc require id", required = true, example = "1")
+			@PathVariable Long kycrId
+	) {
 		return new BaseResponse<>(kycManageService.getCriminalRecord(kycrId));
 	}
 

diff --git a/src/main/java/com/gaseng/kyc/dto/KycRequireSummaryResponse.java b/src/main/java/com/gaseng/kyc/dto/KycRequireSummaryResponse.java
@@ -1,12 +1,18 @@
 package com.gaseng.kyc.dto;
 
-import java.time.LocalDateTime;
-
 import com.gaseng.kyc.domain.KycRequire;
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.time.LocalDateTime;
 
 public record KycRequireSummaryResponse (
+		@Schema(description = "kyc require id", example = "1")
 		Long id,
+
+		@Schema(description = "kyc require member name", example = "홍길동")
 		String name,
+
+		@Schema(description = "kyc require created date", example = "2023-11-08T06:49:55.451533")
 		LocalDateTime createdAt
 ) {
 	public static KycRequireSummaryResponse toResponse(KycRequire require) {

diff --git a/src/main/java/com/gaseng/kyc/dto/KycSaveRequest.java b/src/main/java/com/gaseng/kyc/dto/KycSaveRequest.java
@@ -5,10 +5,14 @@
 import com.gaseng.kyc.domain.KycNoticeStatus;
 import com.gaseng.kyc.domain.KycRequire;
 import com.gaseng.member.domain.Member;
+import io.swagger.v3.oas.annotations.media.Schema;
 
 public record KycSaveRequest (
 		@ValidEnum(enumClass = KycNoticeStatus.class)
+		@Schema(description = "kyc notice status", example = "0 반려 / 1 거절 / 2 승인")
 		KycNoticeStatus status,
+
+		@Schema(description = "kyc notice description", example = "kyc 공지 내용입니다.")
 		String description
 ) {
 	public KycNotice toEntity(Member member, KycRequire require) {