sam-api/app/Swagger/v1/RefreshApi.php

<?php

namespace App\Swagger\v1;

class RefreshApi
{
    /**
     * @OA\Post(
     *     path="/api/v1/refresh",
     *     tags={"Auth"},
     *     summary="토큰 갱신 (리프레시 토큰으로 새로운 액세스 토큰 발급)",
     *     description="리프레시 토큰을 사용하여 새로운 액세스 토큰과 리프레시 토큰을 발급받습니다. 리프레시 토큰은 사용 후 폐기되며 새로운 리프레시 토큰이 발급됩니다.",
     *     security={{"ApiKeyAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(
     *             required={"refresh_token"},
     *
     *             @OA\Property(
     *                 property="refresh_token",
     *                 type="string",
     *                 example="2|def456uvw789",
     *                 description="리프레시 토큰"
     *             )
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=200,
     *         description="토큰 갱신 성공",
     *
     *         @OA\JsonContent(
     *             type="object",
     *
     *             @OA\Property(property="message", type="string", example="토큰이 갱신되었습니다"),
     *             @OA\Property(property="access_token", type="string", example="3|ghi789rst012", description="새로운 액세스 토큰"),
     *             @OA\Property(property="refresh_token", type="string", example="4|jkl012mno345", description="새로운 리프레시 토큰"),
     *             @OA\Property(property="token_type", type="string", example="Bearer", description="토큰 타입"),
     *             @OA\Property(property="expires_in", type="integer", nullable=true, example=7200, description="액세스 토큰 만료 시간 (초 단위, null이면 무제한)"),
     *             @OA\Property(property="expires_at", type="string", nullable=true, example="2025-11-10 18:00:00", description="액세스 토큰 만료 시각 (null이면 무제한)")
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=401,
     *         description="리프레시 토큰이 유효하지 않거나 만료됨",
     *
     *         @OA\JsonContent(
     *
     *             @OA\Property(property="error", type="string", example="리프레시 토큰이 유효하지 않거나 만료되었습니다"),
     *             @OA\Property(property="error_code", type="string", example="TOKEN_EXPIRED", description="에러 코드")
     *         )
     *     ),
     *
     *     @OA\Response(
     *         response=422,
     *         description="검증 실패",
     *
     *         @OA\JsonContent(ref="#/components/schemas/ErrorResponse")
     *     )
     * )
     */
    public function refresh() {}
}