✨ feat/custom/KIKI-71-BE : 커스텀 기능 구현

src/main/java/site/kikihi/custom/platform/adapter/in/web/CustomKeyboardController.java

@@ -24,7 +24,7 @@
 import java.util.UUID;
 
 @RestController
-@RequestMapping("/api/v1/custom")
+@RequestMapping("/api/v1/customs")
 @RequiredArgsConstructor
 public class CustomKeyboardController implements CustomKeyboardControllerSpec {
 
@@ -50,14 +50,14 @@ public ApiResponse<Void> createCustomKeyboard(
     /**
      * 커스텀 키보드 상세 조회
      *
-     * @param customKeyboardId 키보드 상세 조회 ID
+     * @param id 키보드 상세 조회 ID
      */
-    @GetMapping("/{customKeyboardId}")
+    @GetMapping("/{id}")
     public ApiResponse<CustomKeyboardDetailResponse> getCustomKeyboard(
-            @PathVariable Long customKeyboardId
+            @PathVariable Long id
     ) {
         /// 서비스
-        CustomKeyboardWithName keyBoard = service.getCustomKeyboard(customKeyboardId);
+        CustomKeyboardWithName keyBoard = service.getCustomKeyboard(id);
 
         /// DTO 변경
         var response = CustomKeyboardDetailResponse.from(keyBoard);
@@ -71,7 +71,7 @@ public ApiResponse<CustomKeyboardDetailResponse> getCustomKeyboard(
      *
      * @param principalDetails 유저
      */
-    @GetMapping("/myCustoms")
+    @GetMapping()
     public ApiResponse<SliceResponse<CustomKeyboardListResponse>> getMyCustoms(
             @AuthenticationPrincipal PrincipalDetails principalDetails
     ) {
@@ -104,7 +104,7 @@ public ApiResponse<SliceResponse<ProductListResponse>> getCustomKeyboardProducts
             @RequestParam CustomKeyboardLayout layout,
             @RequestParam(required = false) Integer minPrice,
             @RequestParam(required = false) Integer maxPrice,
-            @RequestParam(required = true, defaultValue = "false") boolean bookmark,
+            @RequestParam(defaultValue = "false") boolean bookmark,
             PageRequest pageRequest
     ) {
 
@@ -169,6 +169,7 @@ public ApiResponse<Void> updateCustomKeyboard(
         /// 서비스
         service.insertProductInCustomKeyboard(request.getId(), request.getCategory().getValue(), request.getProductId(), principalDetails.getId());
 
+        /// 수정 완료 응답 제공
         return ApiResponse.updated();
     }
 
@@ -188,7 +189,6 @@ public ApiResponse<Void> deleteCustomKeyboard(
 
         /// 응답
         return ApiResponse.deleted();
-
     }
 
     /**
@@ -198,7 +198,7 @@ public ApiResponse<Void> deleteCustomKeyboard(
      * @param productId         상품 ID
      * @param principalDetails  유저
      */
-    @DeleteMapping()
+    @DeleteMapping("/products")
     public ApiResponse<Void> deleteProductInsideCustom(
             @RequestParam Long id,
             @RequestParam CustomCategoryType category,
@@ -209,6 +209,26 @@ public ApiResponse<Void> deleteProductInsideCustom(
         /// 서비스 호출
         service.deleteCustomInside(id, category.getValue(), productId, principalDetails.getId());
 
+        /// 삭제 완료 응답 제공
         return ApiResponse.deleted();
     }
+
+    /**
+     * 커스텀 키보드 내부 상품 추가 API
+     *
+     * @param request          요청
+     * @param principalDetails 유저
+     */
+    @Override
+    @PatchMapping("/products")
+    public ApiResponse<Void> addProductInsideCustom(
+            @RequestBody @Valid CustomKeyboardUpdateRequest request,
+            @AuthenticationPrincipal PrincipalDetails principalDetails) {
+
+        /// 서비스 호출
+        service.insertProductInCustomKeyboard(request.getId(), request.getCategory().getValue(), request.getProductId(), principalDetails.getId());
+
+        /// 수정 완료 응답 제공
+        return ApiResponse.updated();
+    }
 }

src/main/java/site/kikihi/custom/platform/adapter/in/web/dto/request/bookmark/BookmarkRequest.java

@@ -1,11 +1,10 @@
 package site.kikihi.custom.platform.adapter.in.web.dto.request.bookmark;
 
 import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotNull;
 import lombok.Builder;
 import lombok.Data;
 
-import java.util.UUID;
-
 @Data
 @Builder
 @Schema(
@@ -15,6 +14,7 @@
 public class BookmarkRequest {
 
     @Schema(description = "북마크할 상품 ID", example = "6896ed7d5198cf586e933d6e")
+    @NotNull
     private String productId;
 
 }

src/main/java/site/kikihi/custom/platform/adapter/in/web/dto/request/bookmark/BookmarkSyncRequest.java

@@ -1,14 +1,20 @@
 package site.kikihi.custom.platform.adapter.in.web.dto.request.bookmark;
 
 import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.Valid;
 import lombok.Data;
 
 import java.util.List;
 
 @Data
+@Schema(
+        name = "[요청][북마크] 북마크 싱크 Request",
+        description = "상품을 하번에 북마크할 때 사용하는 요청 DTO입니다."
+)
 public class BookmarkSyncRequest {
 
     @Schema(description = "북마크할 상품들", example = "6896ed7d5198cf586e933d6e")
-    private List<BookmarkRequest> productIds;
+    private List<@Valid BookmarkRequest> productIds;
+
 
 }

src/main/java/site/kikihi/custom/platform/adapter/in/web/dto/request/custom/CustomKeyboardUpdateRequest.java

@@ -1,14 +1,23 @@
 package site.kikihi.custom.platform.adapter.in.web.dto.request.custom;
 
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
 
 @Data
+@Schema(
+        name = "[요청][커스텀] 커스텀 키보드 수정 Request",
+        description = "사용자가 커스텀 키보드의 부품을 수정할 때 사용하는 요청 DTO입니다."
+)
 public class CustomKeyboardUpdateRequest {
 
+    @Parameter(example = "1")
     private Long id;
 
+    @Parameter(example = "housing")
     private CustomCategoryType category;
 
+    @Parameter(example = "68b3f4fedc26d32d8881fe0e")
     private String productId;
 
 }

src/main/java/site/kikihi/custom/platform/adapter/in/web/dto/response/custom/CustomKeyboardDetailResponse.java

@@ -33,12 +33,18 @@ public record CustomKeyboardDetailResponse(
         @Schema(description = "하우징 상품 ID", example = "68b3f4fedc26d32d8881fe12")
         String housingId,
 
+        @Schema(description = "하우징 매핑 이미지 URL", example = "https://example.com/product/101.jpg")
+        String housingImageUrl,
+
         @Schema(description = "하우징(프레임) 이름", example = "TX-65")
         String housingName,
 
         @Schema(description = "키캡 ID", example = "GMK Red Samurai")
         String keyCapId,
 
+        @Schema(description = "키캡 매핑 이미지 URL", example = "https://example.com/product/101.jpg")
+        String keyCapImageUrl,
+
         @Schema(description = "키캡 이름", example = "GMK Red Samurai")
         String keyCapName,
 
@@ -68,8 +74,10 @@ public static CustomKeyboardDetailResponse from(CustomKeyboardWithName entity){
                 .customName(entity.name())
                 .customKeyboardType(entity.layout())
                 .housingId(entity.frameId())
+                .housingImageUrl(entity.frameUrl())
                 .housingName(entity.frameName())
                 .keyCapId(entity.keyCapId())
+                .keyCapImageUrl(entity.keyCapUrl())
                 .keyCapName(entity.keyCapName())
                 .switchId(entity.switchId())
                 .switchName(entity.switchName())

src/main/java/site/kikihi/custom/platform/adapter/in/web/dto/response/custom/CustomKeyboardListResponse.java

@@ -40,6 +40,9 @@ public record CustomKeyboardListResponse(
         @Schema(description = "스위치 이름", example = "Gateron Ink Black v2")
         String switchName,
 
+        @Schema(description = "악세사리 이름", example = "손목 보호대")
+        String accessoryName,
+
         @Schema(description = "썸네일 이미지 URL", example = "https://example.com/custom/101.jpg")
         String thumbnail,
 
@@ -56,6 +59,7 @@ public static CustomKeyboardListResponse from(CustomKeyboardWithName entity){
                 .housingName(entity.frameName())
                 .keyCapName(entity.keyCapName())
                 .switchName(entity.switchName())
+                .accessoryName(entity.accessoryName())
                 .thumbnail(entity.imageUrl())
                 .price(entity.totalPrice())
                 .build();

src/main/java/site/kikihi/custom/platform/adapter/in/web/dto/response/product/KeyboardRecommendationResponse.java

@@ -18,7 +18,10 @@
  */
 
 @Builder
-@Schema(name = "KeyboardRecommendationListResponse", description = "튜토리얼 키보드 추천 리스트 응답")
+@Schema(
+        name = "[응답][튜토리얼] 추천 상품 응답 Response",
+        description = "튜토리얼 키보드 추천 리스트 응답"
+)
 public record KeyboardRecommendationResponse(
 
         @Schema(description = "상품 아이디", example = "101")

src/main/java/site/kikihi/custom/platform/adapter/in/web/dto/response/product/ProductDetailResponse.java

@@ -98,6 +98,10 @@ public static ProductDetailResponse from(Product product, boolean likedByMe) {
 
     /// 내부에서만 사용되는 옵션
     @Builder
+    @Schema(
+            name = "[응답][상품] 상품 옵션 조회 Response",
+            description = "상품의 옵션 정보를 반환하는 응답 DTO입니다."
+    )
     private record ProductOptions(
             String optionName,
             Double price,

src/main/java/site/kikihi/custom/platform/adapter/in/web/dto/response/search/SearchListResponse.java

@@ -1,10 +1,15 @@
 package site.kikihi.custom.platform.adapter.in.web.dto.response.search;
 
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Builder;
 import site.kikihi.custom.platform.domain.search.Search;
 import java.util.List;
 
 @Builder
+@Schema(
+        name = "[응답][검색] 최신 검색어 조회 Response",
+        description = "사용자의 검색어 정보를 반환하는 응답 DTO입니다."
+)
 public record SearchListResponse(
         Long searchId,
         String keyword

src/main/java/site/kikihi/custom/platform/adapter/in/web/swagger/CustomKeyboardControllerSpec.java

@@ -6,7 +6,7 @@
 import site.kikihi.custom.global.response.page.SliceResponse;
 import site.kikihi.custom.platform.adapter.in.web.dto.request.custom.CustomCategoryType;
 import site.kikihi.custom.platform.adapter.in.web.dto.request.custom.CustomKeyboardRequest;
-import site.kikihi.custom.platform.adapter.in.web.dto.response.custom.CustomKeyboardLayoutResponse;
+import site.kikihi.custom.platform.adapter.in.web.dto.request.custom.CustomKeyboardUpdateRequest;
 import site.kikihi.custom.platform.adapter.in.web.dto.response.custom.CustomKeyboardDetailResponse;
 import site.kikihi.custom.platform.adapter.in.web.dto.response.custom.CustomKeyboardListResponse;
 import site.kikihi.custom.platform.adapter.in.web.dto.response.product.ProductListResponse;
@@ -23,8 +23,6 @@
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestParam;
 
-import java.util.List;
-
 @Tag(name = "커스텀 키보드 API", description = "커스텀 키보드 관련 API입니다.")
 public interface CustomKeyboardControllerSpec {
 
@@ -77,9 +75,16 @@ ApiResponse<SliceResponse<CustomKeyboardListResponse>> getMyCustoms(
             @AuthenticationPrincipal PrincipalDetails principalDetails);
 
     /**
+     * 키보드 배열에 따른 목록 조회
      *
+     * @param principalDetails 유저
+     * @param category         카테고리
+     * @param layout           레이아웃
+     * @param minPrice         최소가격
+     * @param maxPrice         최대가격
+     * @param bookmark         북마크 여부
+     * @param pageRequest      페이징
      */
-
     @Operation(
             summary = "키보드 배열에 따른 가능한 부품 조회 API",
             description = "키보드 배열에 따라서 가능한 상품 목록을 조회합니다. 유저의 정보가 들어온다면 북마크 여부 또한 제공합니다."
@@ -90,7 +95,7 @@ ApiResponse<SliceResponse<ProductListResponse>> getCustomKeyboardProductsByLayou
             @RequestParam CustomKeyboardLayout layout,
             @RequestParam(required = false) Integer minPrice,
             @RequestParam(required = false) Integer maxPrice,
-            @RequestParam(required = true) boolean bookmark,
+            @RequestParam(defaultValue = "false") boolean bookmark,
             PageRequest pageRequest
     );
 
@@ -100,10 +105,58 @@ ApiResponse<SliceResponse<ProductListResponse>> getCustomKeyboardProductsByLayou
             description = "JWT를 기반으로 커스텀 키보드를 삭제합니다."
     )
     ApiResponse<Void> deleteCustomKeyboard(
+            @Parameter(example = "1")
             @PathVariable Long id,
+
+            @AuthenticationPrincipal PrincipalDetails principalDetails
+    );
+
+
+    @Operation(
+            summary = "커스텀 키보드 내부 부품 삭제 API",
+            description = "커스텀 키보드 내부 부품을 삭제합니다."
+    )
+    ApiResponse<Void> deleteProductInsideCustom(
+
+            @Parameter(example = "1")
+            @RequestParam Long id,
+
+            @RequestParam CustomCategoryType category,
+
+            @Parameter(example = "68b3f4fedc26d32d8881fe12")
+            @RequestParam String productId,
+
+            @AuthenticationPrincipal PrincipalDetails principalDetails
+    );
+
+
+
+    /**
+     * 내부 부품을 추가
+     * @param request           요청
+     * @param principalDetails  유저
+     */
+    @Operation(
+            summary = "커스텀 키보드 내부 부품 추가 API",
+            description = "커스텀 키보드 내부 부품을 추가합니다.",
+            requestBody = @io.swagger.v3.oas.annotations.parameters.RequestBody(
+                    content = @Content(
+                            mediaType = MediaType.APPLICATION_JSON_VALUE,
+                            examples = {
+                                    @ExampleObject(name = "수정 예시", value = UPDATE_REQUEST),
+                            }
+                    )
+            )
+    )
+    ApiResponse<Void> addProductInsideCustom(
+            @RequestBody @Valid CustomKeyboardUpdateRequest request,
             @AuthenticationPrincipal PrincipalDetails principalDetails
     );
 
+
+
+
+
     String REQUEST = """
             {
               "layout" : "PERCENT_60",
@@ -115,4 +168,12 @@ ApiResponse<Void> deleteCustomKeyboard(
             }
             """;
 
+    String UPDATE_REQUEST = """
+            {
+               "id": "1",
+               "category": "housing",
+               "productId": "68b3f4fedc26d32d8881fe0e"
+             }
+            """;
+
 }