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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(name="Auth", description="로그인/로그아웃/회원가입")
 */

/**
 * 회원가입 요청/응답 스키마
 * -----------------------------------------------------------------------------
 * 필요 시 공용 components 영역으로 이동해도 됩니다.
 */

/**
 * @OA\Schema(
 *     schema="SignupRequest",
 *     type="object",
 *     required={"user_id","name","email","password"},
 *     @OA\Property(property="user_id", type="string", maxLength=255, example="userId", description="로그인 ID (고유)"),
 *     @OA\Property(property="name", type="string", maxLength=255, example="Kent"),
 *     @OA\Property(property="email", type="string", maxLength=100, example="codebridge@gmail.com"),
 *     @OA\Property(property="phone", type="string", maxLength=30, nullable=true, example="010-4820-9104"),
 *     @OA\Property(property="password", type="string", minLength=8, maxLength=64, example="StrongPass!1234")
 * )
 *
 * @OA\Schema(
 *     schema="SignupResponseData",
 *     type="object",
 *     @OA\Property(
 *         property="user",
 *         ref="#/components/schemas/Member"
 *     )
 * )
 *
 * @OA\Schema(
 *    schema="MemberBrief",
 *    type="object",
 *    description="회원 요약 정보(회원가입 응답용)",
 *    required={"id","user_id","name","email","phone"},
 *    @OA\Property(property="id", type="integer", example=6),
 *    @OA\Property(property="user_id", type="string", example="userId"),
 *    @OA\Property(property="name", type="string", example="Kent"),
 *    @OA\Property(property="email", type="string", example="codebridge1@gmail.com"),
 *    @OA\Property(property="phone", type="string", example="010-4820-9104")
 *  )
 *
 */
class AuthApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/debug-apikey",
     *     tags={"Auth"},
     *     summary="API Key 인증 확인",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *     @OA\Response(response=200, description="API Key 인증 성공"),
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function debugApiKey() {}

    /**
     * @OA\Post(
     *     path="/api/v1/login",
     *     tags={"Auth"},
     *     summary="로그인 (토큰 발급)",
     *     security={{"ApiKeyAuth": {}}},
     *     @OA\RequestBody(
     *         required=true,
     *         @OA\JsonContent(
     *             required={"user_id","user_pwd"},
     *             @OA\Property(property="user_id", type="string", example="hamss"),
     *             @OA\Property(property="user_pwd", type="string", example="StrongPass!1234")
     *         )
     *     ),
     *     @OA\Response(
     *         response=200,
     *         description="로그인 성공",
     *         @OA\JsonContent(
     *             type="object",
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string", example="로그인 성공"),
     *             @OA\Property(property="data", type="object",
     *                 @OA\Property(property="user_token", type="string", example="abc123xyz")
     *             )
     *         )
     *     ),
     *     @OA\Response(response=401, description="로그인 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function login() {}

    /**
     * @OA\Post(
     *     path="/api/v1/logout",
     *     tags={"Auth"},
     *     summary="로그아웃 (Access 및 Token 무효화)",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *     @OA\Response(
     *         response=200,
     *         description="로그아웃 성공",
     *         @OA\JsonContent(
     *             @OA\Property(property="success", type="boolean", example=true),
     *             @OA\Property(property="message", type="string", example="로그아웃 성공"),
     *             @OA\Property(property="data", type="null", example=null)
     *         )
     *     ),
     *     @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function logout() {}

    /**
     * @OA\Post(
     *     path="/api/v1/signup",
     *     tags={"Auth"},
     *     summary="회원가입",
     *     description="신규 회원을 생성합니다. (API Key 필요)",
     *     security={{"ApiKeyAuth": {}}},
     *     @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/SignupRequest")),
     *     @OA\Response(
     *         response=200,
     *         description="회원가입 성공",
     *         @OA\JsonContent(
     *             allOf={
     *                 @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *                 @OA\Schema(
     *                     @OA\Property(
     *                         property="data",
     *                         type="object",
     *                         @OA\Property(property="user", ref="#/components/schemas/MemberBrief")
     *                     )
     *                 )
     *             }
     *         )
     *     ),
     *     @OA\Response(response=422, description="검증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *     @OA\Response(response=401, description="인증 실패(API Key 누락/오류)", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function signup() {}
}