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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(name="Menu", description="메뉴 관리(목록/조회/등록/수정/삭제/정렬/토글)")
 */

/**
 * @OA\Schema(
 *   schema="Menu",
 *   type="object",
 *   description="메뉴 상세",
 *   required={"id","name"},
 *   @OA\Property(property="id", type="integer", example=12),
 *   @OA\Property(property="tenant_id", type="integer", nullable=true, example=1, description="null=공용"),
 *   @OA\Property(property="parent_id", type="integer", nullable=true, example=null),
 *   @OA\Property(property="name", type="string", example="메뉴 관리"),
 *   @OA\Property(property="slug", type="string", nullable=true, example="menu.manage"),
 *   @OA\Property(property="url", type="string", nullable=true, example="/admin/menus"),
 *   @OA\Property(property="is_active", type="integer", example=1),
 *   @OA\Property(property="sort_order", type="integer", example=10),
 *   @OA\Property(property="hidden", type="integer", example=0),
 *   @OA\Property(property="is_external", type="integer", example=0),
 *   @OA\Property(property="external_url", type="string", nullable=true, example=null),
 *   @OA\Property(property="icon", type="string", nullable=true, example="list"),
 *   @OA\Property(property="created_at", type="string", format="date-time", example="2025-08-15 10:00:00"),
 *   @OA\Property(property="updated_at", type="string", format="date-time", example="2025-08-15 10:00:00"),
 *   @OA\Property(property="deleted_at", type="string", format="date-time", nullable=true, example=null)
 * )
 *
 * @OA\Schema(
 *   schema="MenuBrief",
 *   type="object",
 *   description="메뉴 요약",
 *   required={"id","name"},
 *   @OA\Property(property="id", type="integer", example=12),
 *   @OA\Property(property="parent_id", type="integer", nullable=true, example=null),
 *   @OA\Property(property="name", type="string", example="메뉴 관리"),
 *   @OA\Property(property="slug", type="string", nullable=true, example="menu.manage"),
 *   @OA\Property(property="url", type="string", nullable=true, example="/admin/menus"),
 *   @OA\Property(property="is_active", type="integer", example=1),
 *   @OA\Property(property="sort_order", type="integer", example=10),
 *   @OA\Property(property="hidden", type="integer", example=0),
 *   @OA\Property(property="is_external", type="integer", example=0),
 *   @OA\Property(property="external_url", type="string", nullable=true, example=null),
 *   @OA\Property(property="icon", type="string", nullable=true, example="list")
 * )
 *
 * @OA\Schema(
 *   schema="MenuList",
 *   type="array",
 *   @OA\Items(ref="#/components/schemas/MenuBrief")
 * )
 *
 * @OA\Schema(
 *   schema="MenuCreateRequest",
 *   type="object",
 *   required={"name"},
 *   @OA\Property(property="parent_id", type="integer", nullable=true, example=null, description="상위 메뉴 ID"),
 *   @OA\Property(property="name", type="string", example="새 메뉴", description="메뉴명"),
 *   @OA\Property(property="slug", type="string", nullable=true, example="menu.new", description="권한 키로도 활용"),
 *   @OA\Property(property="url", type="string", nullable=true, example="/admin/new"),
 *   @OA\Property(property="is_active", type="boolean", example=true),
 *   @OA\Property(property="sort_order", type="integer", example=0),
 *   @OA\Property(property="hidden", type="boolean", example=false),
 *   @OA\Property(property="is_external", type="boolean", example=false),
 *   @OA\Property(property="external_url", type="string", nullable=true, example=null),
 *   @OA\Property(property="icon", type="string", nullable=true, example="plus")
 * )
 *
 * @OA\Schema(
 *   schema="MenuUpdateRequest",
 *   type="object",
 *   @OA\Property(property="parent_id", type="integer", nullable=true, example=null),
 *   @OA\Property(property="name", type="string", example="메뉴명 변경"),
 *   @OA\Property(property="slug", type="string", nullable=true, example="menu.changed"),
 *   @OA\Property(property="url", type="string", nullable=true, example="/admin/changed"),
 *   @OA\Property(property="is_active", type="boolean", example=true),
 *   @OA\Property(property="sort_order", type="integer", example=5),
 *   @OA\Property(property="hidden", type="boolean", example=false),
 *   @OA\Property(property="is_external", type="boolean", example=false),
 *   @OA\Property(property="external_url", type="string", nullable=true, example=null),
 *   @OA\Property(property="icon", type="string", nullable=true, example="edit")
 * )
 */
class MenuApi
{
    /**
     * @OA\Get(
     *   path="/api/v1/menus",
     *   summary="메뉴 목록 조회",
     *   description="테넌트 범위 내(또는 공용) 메뉴 목록을 반환합니다. parent_id/is_active/hidden 필터 지원.",
     *   tags={"Menu"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *   @OA\Parameter(name="parent_id", in="query", required=false, @OA\Schema(type="integer", example=0)),
     *   @OA\Parameter(name="is_active", in="query", required=false, @OA\Schema(type="integer", example=1)),
     *   @OA\Parameter(name="hidden", in="query", required=false, @OA\Schema(type="integer", example=0)),
     *   @OA\Response(response=200, description="목록 조회 성공",
     *     @OA\JsonContent(allOf={@OA\Schema(ref="#/components/schemas/ApiResponse"), @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/MenuList"))})
     *   ),
     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function index() {}

    /**
     * @OA\Get(
     *   path="/api/v1/menus/{id}",
     *   summary="메뉴 단건 조회",
     *   description="ID로 메뉴 상세 정보를 조회합니다.",
     *   tags={"Menu"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=12)),
     *   @OA\Response(response=200, description="단건 조회 성공",
     *     @OA\JsonContent(allOf={@OA\Schema(ref="#/components/schemas/ApiResponse"), @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Menu"))})
     *   ),
     *   @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function show() {}

    /**
     * @OA\Post(
     *   path="/api/v1/menus",
     *   summary="메뉴 등록",
     *   description="새로운 메뉴를 등록합니다.",
     *   tags={"Menu"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/MenuCreateRequest")),
     *   @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="id", type="integer", example=12)))})
     *   ),
     *   @OA\Response(response=400, description="파라미터 오류", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\ResponsE(response=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function store() {}

    /**
     * @OA\Patch(
     *   path="/api/v1/menus/{id}",
     *   summary="메뉴 수정",
     *   description="기존 메뉴 정보를 수정합니다(부분 수정).",
     *   tags={"Menu"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=12)),
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/MenuUpdateRequest")),
     *   @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="id", type="integer", example=12)))})
     *   ),
     *   @OA\Response(response=400, description="파라미터 오류", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function update() {}

    /**
     * @OA\Delete(
     *   path="/api/v1/menus/{id}",
     *   summary="메뉴 삭제(소프트 삭제)",
     *   description="지정한 메뉴를 소프트 삭제합니다.",
     *   tags={"Menu"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=12)),
     *   @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="id", type="integer", example=12), @OA\Property(property="deleted", type="boolean", example=true)))})
     *   ),
     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function destroy() {}

    /**
     * @OA\Post(
     *   path="/api/v1/menus/reorder",
     *   summary="메뉴 정렬 변경",
     *   description="여러 메뉴의 sort_order를 일괄 변경합니다.",
     *   tags={"Menu"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *   @OA\RequestBody(required=true, @OA\JsonContent(
     *     type="array",
     *     @OA\Items(type="object",
     *       @OA\Property(property="id", type="integer", example=12),
     *       @OA\Property(property="sort_order", type="integer", example=1)
     *     )
     *   )),
     *   @OA\Response(response=200, description="정렬 변경 성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse")),
     *   @OA\Response(response=400, description="파라미터 오류", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function reorder() {}

    /**
     * @OA\Post(
     *   path="/api/v1/menus/{id}/toggle",
     *   summary="메뉴 상태 토글",
     *   description="is_active / hidden / is_external 중 하나 이상을 토글합니다.",
     *   tags={"Menu"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=12)),
     *   @OA\RequestBody(required=true, @OA\JsonContent(type="object",
     *     @OA\Property(property="is_active", type="boolean", nullable=true, example=true),
     *     @OA\Property(property="hidden", type="boolean", nullable=true, example=false),
     *     @OA\Property(property="is_external", type="boolean", nullable=true, example=false)
     *   )),
     *   @OA\Response(response=200, description="토글 성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse")),
     *   @OA\Response(response=400, description="파라미터 오류", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=404, description="데이터 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
     * )
     */
    public function toggle() {}
}