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

<?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() {}
}