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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *     name="NotificationSetting",
 *     description="알림 설정 관리"
 * )
 *
 * @OA\Schema(
 *     schema="NotificationSettingItem",
 *     type="object",
 *
 *     @OA\Property(property="notification_type", type="string", example="approval"),
 *     @OA\Property(property="label", type="string", example="전자결재"),
 *     @OA\Property(property="push_enabled", type="boolean", example=true),
 *     @OA\Property(property="email_enabled", type="boolean", example=false),
 *     @OA\Property(property="sms_enabled", type="boolean", example=false),
 *     @OA\Property(property="in_app_enabled", type="boolean", example=true),
 *     @OA\Property(property="kakao_enabled", type="boolean", example=false),
 *     @OA\Property(property="settings", type="object", nullable=true)
 * )
 *
 * @OA\Schema(
 *     schema="NotificationSettingResponse",
 *     type="object",
 *
 *     @OA\Property(
 *         property="settings",
 *         type="object",
 *         additionalProperties={"$ref": "#/components/schemas/NotificationSettingItem"}
 *     ),
 *     @OA\Property(
 *         property="types",
 *         type="object",
 *         description="알림 유형 레이블",
 *         example={"approval": "전자결재", "order": "수주", "deposit": "입금"}
 *     ),
 *     @OA\Property(
 *         property="channels",
 *         type="object",
 *         description="채널 레이블",
 *         example={"push": "푸시 알림", "email": "이메일", "sms": "SMS"}
 *     )
 * )
 *
 * @OA\Schema(
 *     schema="UpdateNotificationSettingRequest",
 *     type="object",
 *     required={"notification_type"},
 *
 *     @OA\Property(property="notification_type", type="string", enum={"approval", "order", "deposit", "withdrawal", "notice", "system", "marketing", "security"}, example="approval", description="알림 유형"),
 *     @OA\Property(property="push_enabled", type="boolean", nullable=true, example=true, description="푸시 알림 활성화"),
 *     @OA\Property(property="email_enabled", type="boolean", nullable=true, example=false, description="이메일 알림 활성화"),
 *     @OA\Property(property="sms_enabled", type="boolean", nullable=true, example=false, description="SMS 알림 활성화"),
 *     @OA\Property(property="in_app_enabled", type="boolean", nullable=true, example=true, description="인앱 알림 활성화"),
 *     @OA\Property(property="kakao_enabled", type="boolean", nullable=true, example=false, description="카카오 알림톡 활성화"),
 *     @OA\Property(property="settings", type="object", nullable=true, description="추가 설정")
 * )
 *
 * @OA\Schema(
 *     schema="BulkUpdateNotificationSettingRequest",
 *     type="object",
 *     required={"settings"},
 *
 *     @OA\Property(
 *         property="settings",
 *         type="array",
 *
 *         @OA\Items(ref="#/components/schemas/UpdateNotificationSettingRequest")
 *     )
 * )
 */
class NotificationSettingApi
{
    /**
     * @OA\Get(
     *     path="/api/v1/users/me/notification-settings",
     *     operationId="getNotificationSettings",
     *     tags={"NotificationSetting"},
     *     summary="알림 설정 조회",
     *     description="현재 사용자의 알림 설정을 조회합니다.",
     *     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", ref="#/components/schemas/NotificationSettingResponse")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패")
     * )
     */
    public function index() {}

    /**
     * @OA\Put(
     *     path="/api/v1/users/me/notification-settings",
     *     operationId="updateNotificationSetting",
     *     tags={"NotificationSetting"},
     *     summary="알림 설정 업데이트",
     *     description="특정 알림 유형의 설정을 업데이트합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/UpdateNotificationSettingRequest")
     *     ),
     *
     *     @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", ref="#/components/schemas/NotificationSettingItem")
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=422, description="유효성 검증 실패")
     * )
     */
    public function update() {}

    /**
     * @OA\Put(
     *     path="/api/v1/users/me/notification-settings/bulk",
     *     operationId="bulkUpdateNotificationSettings",
     *     tags={"NotificationSetting"},
     *     summary="알림 설정 일괄 업데이트",
     *     description="여러 알림 유형의 설정을 일괄 업데이트합니다.",
     *     security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
     *
     *     @OA\RequestBody(
     *         required=true,
     *
     *         @OA\JsonContent(ref="#/components/schemas/BulkUpdateNotificationSettingRequest")
     *     ),
     *
     *     @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="array",
     *
     *                 @OA\Items(ref="#/components/schemas/NotificationSettingItem")
     *             )
     *         )
     *     ),
     *
     *     @OA\Response(response=401, description="인증 실패"),
     *     @OA\Response(response=422, description="유효성 검증 실패")
     * )
     */
    public function bulkUpdate() {}
}