From 81a6dfab5afc964909d72a766c07d3c51099c311 Mon Sep 17 00:00:00 2001
From: hskwon <shine1324@gmail.com>
Date: Thu, 18 Dec 2025 22:08:08 +0900
Subject: [PATCH] =?UTF-8?q?fix:=20Swagger=20=EA=B2=BD=EB=A1=9C=20=EC=88=98?=
 =?UTF-8?q?=EC=A0=95=20=EB=B0=8F=20Internal=20API=20=EB=AC=B8=EC=84=9C=20?=
 =?UTF-8?q?=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- PushApi: /api/push → /api/v1/push 경로 수정
- InternalApi: exchange-token 엔드포인트 Swagger 문서 추가
---
 app/Swagger/v1/InternalApi.php | 77 ++++++++++++++++++++++++++++++++++
 app/Swagger/v1/PushApi.php     | 12 +++---
 2 files changed, 83 insertions(+), 6 deletions(-)
 create mode 100644 app/Swagger/v1/InternalApi.php

diff --git a/app/Swagger/v1/InternalApi.php b/app/Swagger/v1/InternalApi.php
new file mode 100644
index 0000000..3d90bf8
--- /dev/null
+++ b/app/Swagger/v1/InternalApi.php
@@ -0,0 +1,77 @@
+<?php
+
+namespace App\Swagger\v1;
+
+/**
+ * @OA\Tag(name="Internal", description="내부 서버간 통신 API (HMAC 인증)")
+ */
+
+/**
+ * Internal 관련 스키마 정의
+ * -----------------------------------------------------------------------------
+ */
+
+/**
+ * @OA\Schema(
+ *     schema="ExchangeTokenRequest",
+ *     type="object",
+ *     required={"user_id", "tenant_id", "exp", "signature"},
+ *
+ *     @OA\Property(property="user_id", type="integer", example=1, description="사용자 ID"),
+ *     @OA\Property(property="tenant_id", type="integer", example=1, description="테넌트 ID"),
+ *     @OA\Property(property="exp", type="integer", example=1734567890, description="만료 시간 (Unix timestamp)"),
+ *     @OA\Property(property="signature", type="string", example="a1b2c3d4e5f6...", description="HMAC 서명값")
+ * )
+ *
+ * @OA\Schema(
+ *     schema="ExchangeTokenResponse",
+ *     type="object",
+ *
+ *     @OA\Property(property="token", type="string", example="1|abc123def456...", description="발급된 Sanctum 토큰"),
+ *     @OA\Property(property="token_type", type="string", example="Bearer", description="토큰 타입"),
+ *     @OA\Property(property="expires_at", type="string", format="date-time", example="2025-12-18 12:00:00", description="토큰 만료 시간")
+ * )
+ */
+class InternalApi
+{
+    /**
+     * @OA\Post(
+     *     path="/api/v1/internal/exchange-token",
+     *     tags={"Internal"},
+     *     summary="토큰 교환",
+     *     description="MNG 서버에서 HMAC 서명된 페이로드로 API Sanctum 토큰을 발급받습니다. API Key 및 Bearer 인증이 필요하지 않습니다.",
+     *
+     *     @OA\RequestBody(
+     *         required=true,
+     *
+     *         @OA\JsonContent(ref="#/components/schemas/ExchangeTokenRequest")
+     *     ),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="토큰 교환 성공",
+     *
+     *         @OA\JsonContent(
+     *             allOf={
+     *
+     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *                 @OA\Schema(
+     *
+     *                     @OA\Property(property="message", type="string", example="토큰이 교환되었습니다."),
+     *                     @OA\Property(property="data", ref="#/components/schemas/ExchangeTokenResponse")
+     *                 )
+     *             }
+     *         )
+     *     ),
+     *
+     *     @OA\Response(
+     *         response=401,
+     *         description="인증 실패 (HMAC 서명 불일치 또는 만료)",
+     *
+     *         @OA\JsonContent(ref="#/components/schemas/ErrorResponse")
+     *     ),
+     *     @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function exchangeToken() {}
+}
\ No newline at end of file
diff --git a/app/Swagger/v1/PushApi.php b/app/Swagger/v1/PushApi.php
index 2985212..f0dba72 100644
--- a/app/Swagger/v1/PushApi.php
+++ b/app/Swagger/v1/PushApi.php
@@ -114,7 +114,7 @@ class PushApi
 {
     /**
      * @OA\Post(
-     *     path="/api/push/register-token",
+     *     path="/api/v1/push/register-token",
      *     tags={"Push"},
      *     summary="FCM 토큰 등록",
      *     description="디바이스의 FCM 토큰을 등록합니다. 동일한 토큰이 이미 존재하면 업데이트됩니다.",
@@ -151,7 +151,7 @@ public function registerToken() {}
 
     /**
      * @OA\Post(
-     *     path="/api/push/unregister-token",
+     *     path="/api/v1/push/unregister-token",
      *     tags={"Push"},
      *     summary="FCM 토큰 해제",
      *     description="디바이스의 FCM 토큰을 비활성화합니다.",
@@ -192,7 +192,7 @@ public function unregisterToken() {}
 
     /**
      * @OA\Get(
-     *     path="/api/push/tokens",
+     *     path="/api/v1/push/tokens",
      *     tags={"Push"},
      *     summary="사용자 토큰 목록 조회",
      *     description="현재 사용자의 활성화된 디바이스 토큰 목록을 조회합니다.",
@@ -226,7 +226,7 @@ public function getTokens() {}
 
     /**
      * @OA\Get(
-     *     path="/api/push/settings",
+     *     path="/api/v1/push/settings",
      *     tags={"Push"},
      *     summary="알림 설정 조회",
      *     description="현재 사용자의 알림 유형별 설정을 조회합니다. 설정이 없는 유형은 기본값으로 반환됩니다.",
@@ -266,7 +266,7 @@ public function getSettings() {}
 
     /**
      * @OA\Put(
-     *     path="/api/push/settings",
+     *     path="/api/v1/push/settings",
      *     tags={"Push"},
      *     summary="알림 설정 업데이트",
      *     description="사용자의 알림 설정을 업데이트합니다. 여러 알림 유형을 한 번에 설정할 수 있습니다.",
@@ -308,7 +308,7 @@ public function updateSettings() {}
 
     /**
      * @OA\Get(
-     *     path="/api/push/notification-types",
+     *     path="/api/v1/push/notification-types",
      *     tags={"Push"},
      *     summary="알림 유형 목록 조회",
      *     description="지원하는 알림 유형과 알림음 목록을 조회합니다.",