diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
index 5463e95..8807dc9 100644
--- a/.github/workflows/deploy.yml
+++ b/.github/workflows/deploy.yml
@@ -7,45 +7,54 @@ on:
 jobs:
   deploy:
     runs-on: ubuntu-latest
-    env:
-      KEY_hackerton: ${{ secrets.KEY_HACKERTON_PROD }} # 운영용 secret
 
     steps:
-      # 1️⃣ 코드 체크아웃
+      # 1. 코드 체크아웃
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
-      # 2️⃣ JDK 17 세팅
-      - name: Set up JDK
-        uses: actions/setup-java@v3
+      # 2. JDK 17 세팅
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
         with:
           distribution: 'temurin'
           java-version: '17'
 
-      # 3️⃣ 빌드 + jar 이름 고정
-      - name: Build
-        run: |
-          ./gradlew clean bootJar -x test
-          cp build/libs/*SNAPSHOT.jar build/libs/app.jar
+      # 3. Gradle 실행 권한 부여
+      - name: Grant execute permission for gradlew
+        run: chmod +x ./gradlew
 
-      # 4️⃣ EC2로 jar 전송
+      # 4. Gradle 빌드
+      - name: Build with Gradle
+        run: ./gradlew clean bootJar -x test
+
+      # 5. jar 파일 이름 고정
+      - name: Rename jar
+        run: mv build/libs/*.jar build/libs/app.jar
+
+      # 6. EC2로 jar 전송
       - name: Upload jar to EC2
-        uses: appleboy/scp-action@v0.1.4
+        uses: appleboy/scp-action@v0.1.7
         with:
           host: ${{ secrets.EC2_HOST }}
           username: ${{ secrets.EC2_USER }}
           key: ${{ secrets.EC2_KEY }}
           source: "build/libs/app.jar"
-          target: "/home/ubuntu/app/"
+          target: "/home/ubuntu/app"
+          strip_components: 2
 
-      # 5️⃣ EC2에서 앱 재시작
-      - name: Run app on EC2
-        uses: appleboy/ssh-action@v0.1.8
+      # 7. EC2에서 앱 재시작
+      - name: Restart app on EC2
+        uses: appleboy/ssh-action@v1.0.3
         with:
           host: ${{ secrets.EC2_HOST }}
           username: ${{ secrets.EC2_USER }}
           key: ${{ secrets.EC2_KEY }}
+          envs: KEY_HACKERTON
           script: |
-            cd /home/ubuntu/app/
+            cd /home/ubuntu/app
             chmod +x run.sh
+            export KEY_hackerton="$KEY_HACKERTON"
             ./run.sh
+        env:
+          KEY_HACKERTON: ${{ secrets.KEY_HACKERTON }}
diff --git a/src/main/java/com/example/demo/domain/gemini/controller/GeminiController.java b/src/main/java/com/example/demo/domain/gemini/controller/GeminiController.java
index ce49016..b5c8287 100644
--- a/src/main/java/com/example/demo/domain/gemini/controller/GeminiController.java
+++ b/src/main/java/com/example/demo/domain/gemini/controller/GeminiController.java
@@ -5,6 +5,10 @@
 import com.example.demo.shared.response.ApiResponse;
 import com.example.demo.shared.response.ErrorCode;
 import com.example.demo.shared.response.SuccessCode;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.ExampleObject;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
@@ -18,6 +22,22 @@ public class GeminiController {
 
     private final GeminiService geminiService;
 
+    @Operation(
+            summary = "감정 배출 및 키워드 추출",
+            description = "유저의 감정(content)을 보내면 gemini가 답변과 핵심 키워드를 반환합니다."
+    )
+    @io.swagger.v3.oas.annotations.parameters.RequestBody(
+            description = "상담할 고민 내용",
+            required = true,
+            content = @Content(
+                    mediaType = "application/json",
+                    schema = @Schema(example = "{\"content\": \"오늘 해커톤 너무 힘들다.\"}"),
+                    examples = @ExampleObject(
+                            name = "고민 상담 예시",
+                            value = "{\"content\": \"해커톤 프로젝트가 생각보다 어려워서 속상해...\"}"
+                    )
+            )
+    )
     @PostMapping("/ask")
     public ApiResponse<Map<String, Object>> ask(@RequestBody Map<String, String> request) {
         String userContent = request.get("content");
diff --git a/src/main/java/com/example/demo/domain/ranking/controller/RankingController.java b/src/main/java/com/example/demo/domain/ranking/controller/RankingController.java
index c2507e1..003519e 100644
--- a/src/main/java/com/example/demo/domain/ranking/controller/RankingController.java
+++ b/src/main/java/com/example/demo/domain/ranking/controller/RankingController.java
@@ -3,6 +3,10 @@
 import com.example.demo.domain.ranking.service.RankingService;
 import com.example.demo.shared.response.ApiResponse;
 import com.example.demo.shared.response.SuccessCode;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.media.Content;
+import io.swagger.v3.oas.annotations.media.ExampleObject;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.RequiredArgsConstructor;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.RequestMapping;
@@ -18,6 +22,10 @@ public class RankingController {
 
     private final RankingService rankingService;
 
+    @Operation(
+            summary = "TOP3 키워드 반환",
+            description = "TOP3 키워드를 반환합니다."
+    )
     @GetMapping("/top3")
     public ApiResponse<List<Map<String, Object>>> getTop3() {
         List<Map<String, Object>> result = rankingService.getTop3WithPercentage();