[refactor/egg-api]

src/main/java/org/runimo/runimo/user/controller/EggController.java

@@ -1,5 +1,8 @@
 package org.runimo.runimo.user.controller;
 
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
@@ -26,8 +29,14 @@ public class EggController {
   private final GiveLovePointToEggUsecase giveLovePointToEggUsecase;
   private final IncubatingEggQueryUsecase incubatingEggQueryUsecase;
 
+  @Operation(summary = "알 등록", description = "사용자가 알을 부화기에 등록합니다.")
+  @ApiResponses(value = {
+      @ApiResponse(responseCode = "201", description = "알 등록 성공"),
+      @ApiResponse(responseCode = "400", description = "잘못된 요청 데이터"),
+      @ApiResponse(responseCode = "401", description = "인증 실패")
+  })
   @PostMapping
-  public ResponseEntity<SuccessResponse<RegisterEggResponse>> registerEgg(
+  public ResponseEntity<SuccessResponse<RegisterEggResponse>> registerEggToIncubator(
       @UserId Long userId,
       @Valid @RequestBody RegisterEggRequest request
   ) {
@@ -41,13 +50,19 @@ public ResponseEntity<SuccessResponse<RegisterEggResponse>> registerEgg(
         ));
   }
 
+  @Operation(summary = "애정 포인트 사용", description = "사용자가 알에 애정 포인트를 사용합니다.")
+  @ApiResponses(value ={
+      @ApiResponse(responseCode = "200", description = "애정 포인트 사용 성공"),
+      @ApiResponse(responseCode = "400", description = "잘못된 요청 데이터"),
+      @ApiResponse(responseCode = "401", description = "인증 실패")
+  })
   @PatchMapping
-  public ResponseEntity<SuccessResponse<UseLovePointResponse>> useLovePoint(
+  public ResponseEntity<SuccessResponse<UseLovePointResponse>> useLovePointToEgg(
       @UserId Long userId,
       @Valid @RequestBody UseLovePointRequest request
   ) {
     UseLovePointResponse useLovePointResponse = giveLovePointToEggUsecase.execute(
-        new UseLovePointCommand(userId, request.itemId(), request.lovePointAmount())
+        new UseLovePointCommand(userId, request.incubatingEggId(), request.lovePointAmount())
     );
     return ResponseEntity.ok().body(
         SuccessResponse.of(
@@ -56,8 +71,13 @@ public ResponseEntity<SuccessResponse<UseLovePointResponse>> useLovePoint(
         ));
   }
 
+  @Operation(summary = "부화중인 알 조회", description = "사용자가 부화중인 알을 조회합니다.")
+  @ApiResponses(value = {
+      @ApiResponse(responseCode = "200", description = "부화중인 알 조회 성공"),
+      @ApiResponse(responseCode = "401", description = "인증 실패")
+  })
   @GetMapping
-  public ResponseEntity<SuccessResponse<QueryIncubatingEggResponse>> getEgg(
+  public ResponseEntity<SuccessResponse<QueryIncubatingEggResponse>> getIncubatingEgg(
       @UserId Long userId
   ) {
     QueryIncubatingEggResponse response = incubatingEggQueryUsecase.execute(userId);

src/main/java/org/runimo/runimo/user/controller/request/RegisterEggRequest.java

@@ -1,6 +1,16 @@
 package org.runimo.runimo.user.controller.request;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema(
+    description = "부화할 알 등록 요청",
+    example = """
+        {
+          "item_id": 1
+        }
+        """)
 public record RegisterEggRequest(
+    @Schema(description = "부화할 알 ID (보유중인 알)", example = "1")
     Long itemId
 ) {
 }

src/main/java/org/runimo/runimo/user/controller/request/UseLovePointRequest.java

@@ -1,7 +1,19 @@
 package org.runimo.runimo.user.controller.request;
 
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema(
+    description = "사랑의 포인트 사용 요청",
+    example = """
+        {
+          "incubating_egg_id": 1,
+          "love_point_amount": 100
+        }
+        """)
 public record UseLovePointRequest(
-    Long itemId,
+    @Schema(description = "부화중인 알 ID", example = "1")
+    Long incubatingEggId,
+    @Schema(description = "사용할 사랑의 포인트", example = "100")
     Long lovePointAmount
 ) {
 }