From 868b7656581f07e634d0e591878d5bf12a4257f5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=EA=B6=8C=ED=98=81=EC=84=B1?= <shine1324@gmail.com>
Date: Fri, 30 Jan 2026 21:06:14 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20=EC=95=B1=20=EB=B2=84=EC=A0=84=20API=20?=
 =?UTF-8?q?Swagger=20=EB=AC=B8=EC=84=9C=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- App Version 태그 (latestVersion, download)
- AppVersionCheckResponse, AppVersionLatest 스키마 정의

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 app/Swagger/v1/AppVersionApi.php | 126 +++++++++++++++++++++++++++++++
 1 file changed, 126 insertions(+)
 create mode 100644 app/Swagger/v1/AppVersionApi.php

diff --git a/app/Swagger/v1/AppVersionApi.php b/app/Swagger/v1/AppVersionApi.php
new file mode 100644
index 0000000..8b5f797
--- /dev/null
+++ b/app/Swagger/v1/AppVersionApi.php
@@ -0,0 +1,126 @@
+<?php
+
+namespace App\Swagger\v1;
+
+/**
+ * @OA\Tag(name="App Version", description="앱 버전 관리 (인앱 업데이트)")
+ */
+
+/**
+ * App Version 관련 스키마 정의
+ * -----------------------------------------------------------------------------
+ */
+
+/**
+ * @OA\Schema(
+ *     schema="AppVersionLatest",
+ *     type="object",
+ *     description="최신 앱 버전 정보",
+ *
+ *     @OA\Property(property="id", type="integer", example=3),
+ *     @OA\Property(property="version_code", type="integer", example=2, description="정수 비교용 버전 코드"),
+ *     @OA\Property(property="version_name", type="string", example="0.2", description="표시용 버전명"),
+ *     @OA\Property(property="release_notes", type="string", nullable=true, example="- 알림음 채널 정리\n- 인앱 업데이트 추가", description="변경사항"),
+ *     @OA\Property(property="force_update", type="boolean", example=false, description="강제 업데이트 여부"),
+ *     @OA\Property(property="apk_size", type="integer", nullable=true, example=15728640, description="APK 파일 크기(bytes)"),
+ *     @OA\Property(property="download_url", type="string", example="https://api.codebridge-x.com/api/v1/app/download/3", description="APK 다운로드 URL"),
+ *     @OA\Property(property="published_at", type="string", format="date", nullable=true, example="2026-01-30", description="배포일")
+ * )
+ *
+ * @OA\Schema(
+ *     schema="AppVersionCheckResponse",
+ *     type="object",
+ *     description="버전 확인 응답",
+ *
+ *     @OA\Property(property="has_update", type="boolean", example=true, description="업데이트 존재 여부"),
+ *     @OA\Property(
+ *         property="latest_version",
+ *         nullable=true,
+ *         ref="#/components/schemas/AppVersionLatest",
+ *         description="최신 버전 정보 (has_update=false면 null)"
+ *     )
+ * )
+ */
+class AppVersionApi
+{
+    /**
+     * @OA\Get(
+     *     path="/api/v1/app/version",
+     *     tags={"App Version"},
+     *     summary="최신 버전 확인",
+     *     description="현재 앱 버전과 서버의 최신 버전을 비교하여 업데이트 필요 여부를 반환합니다. Bearer 토큰 불필요, API Key만 필요합니다.",
+     *     security={{"ApiKeyAuth": {}}},
+     *
+     *     @OA\Parameter(
+     *         name="platform",
+     *         in="query",
+     *         required=false,
+     *         description="플랫폼 (기본값: android)",
+     *
+     *         @OA\Schema(type="string", enum={"android", "ios"}, example="android")
+     *     ),
+     *
+     *     @OA\Parameter(
+     *         name="current_version_code",
+     *         in="query",
+     *         required=true,
+     *         description="현재 앱의 버전 코드 (정수)",
+     *
+     *         @OA\Schema(type="integer", example=1)
+     *     ),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="버전 확인 성공",
+     *
+     *         @OA\JsonContent(
+     *             allOf={
+     *
+     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
+     *                 @OA\Schema(
+     *
+     *                     @OA\Property(property="data", ref="#/components/schemas/AppVersionCheckResponse")
+     *                 )
+     *             }
+     *         )
+     *     ),
+     *
+     *     @OA\Response(response=401, description="API Key 인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function latestVersion() {}
+
+    /**
+     * @OA\Get(
+     *     path="/api/v1/app/download/{id}",
+     *     tags={"App Version"},
+     *     summary="APK 다운로드",
+     *     description="지정된 버전의 APK 파일을 다운로드합니다. 다운로드 카운트가 자동으로 증가합니다. Bearer 토큰 불필요, API Key만 필요합니다.",
+     *     security={{"ApiKeyAuth": {}}},
+     *
+     *     @OA\Parameter(
+     *         name="id",
+     *         in="path",
+     *         required=true,
+     *         description="앱 버전 ID",
+     *
+     *         @OA\Schema(type="integer", example=3)
+     *     ),
+     *
+     *     @OA\Response(
+     *         response=200,
+     *         description="APK 파일 다운로드",
+     *
+     *         @OA\MediaType(
+     *             mediaType="application/vnd.android.package-archive",
+     *
+     *             @OA\Schema(type="string", format="binary")
+     *         )
+     *     ),
+     *
+     *     @OA\Response(response=404, description="APK 파일을 찾을 수 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
+     *     @OA\Response(response=401, description="API Key 인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
+     * )
+     */
+    public function download() {}
+}