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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *   name="RolePermission",
 *   description="역할-퍼미션 매핑(조회/부여/회수/동기화)"
 * )
 */

/**
 * @OA\Schema(
 *   schema="PermissionBrief",
 *   type="object",
 *   description="퍼미션 요약",
 *   required={"id","name","guard_name"},
 *   @OA\Property(property="id", type="integer", example=15),
 *   @OA\Property(property="tenant_id", type="integer", example=1),
 *   @OA\Property(property="name", type="string", example="menu:101.view"),
 *   @OA\Property(property="guard_name", type="string", example="api"),
 *   @OA\Property(property="created_at", type="string", format="date-time", example="2025-08-16 10:00:00"),
 *   @OA\Property(property="updated_at", type="string", format="date-time", example="2025-08-16 10:00:00")
 * )
 *
 * @OA\Schema(
 *   schema="PermissionList",
 *   type="array",
 *   @OA\Items(ref="#/components/schemas/PermissionBrief")
 * )
 *
 * @OA\Schema(
 *   schema="RolePermissionGrantRequest",
 *   type="object",
 *   description="역할에 퍼미션 부여. 방법 A: permission_names 배열. 방법 B: menus + actions 조합.",
 *   oneOf={
 *     @OA\Schema(
 *       description="방법 A: 퍼미션 이름 배열",
 *       required={"permission_names"},
 *       @OA\Property(property="permission_names", type="array", @OA\Items(type="string"), example={"menu:101.view","menu:101.create"})
 *     ),
 *     @OA\Schema(
 *       description="방법 B: 메뉴+액션 조합",
 *       required={"menus","actions"},
 *       @OA\Property(property="menus", type="array", @OA\Items(type="integer"), example={101,102}),
 *       @OA\Property(property="actions", type="array", @OA\Items(type="string"), example={"view","create","update","delete"})
 *     )
 *   }
 * )
 *
 * @OA\Schema(
 *   schema="RolePermissionRevokeRequest",
 *   type="object",
 *   description="역할에서 퍼미션 회수. 방법 A: permission_names 배열. 방법 B: menus + actions 조합.",
 *   oneOf={
 *     @OA\Schema(
 *       description="방법 A: 퍼미션 이름 배열",
 *       required={"permission_names"},
 *       @OA\Property(property="permission_names", type="array", @OA\Items(type="string"), example={"menu:101.view","menu:101.create"})
 *     ),
 *     @OA\Schema(
 *       description="방법 B: 메뉴+액션 조합",
 *       required={"menus","actions"},
 *       @OA\Property(property="menus", type="array", @OA\Items(type="integer"), example={101}),
 *       @OA\Property(property="actions", type="array", @OA\Items(type="string"), example={"create"})
 *     )
 *   }
 * )
 *
 * @OA\Schema(
 *   schema="RolePermissionSyncRequest",
 *   type="object",
 *   description="역할의 퍼미션을 전달된 목록으로 완전히 교체(동기화). 방법 A 또는 B.",
 *   oneOf={
 *     @OA\Schema(
 *       description="방법 A: 퍼미션 이름 배열",
 *       required={"permission_names"},
 *       @OA\Property(property="permission_names", type="array", @OA\Items(type="string"), example={"menu:101.view","menu:101.update"})
 *     ),
 *     @OA\Schema(
 *       description="방법 B: 메뉴+액션 조합",
 *       required={"menus","actions"},
 *       @OA\Property(property="menus", type="array", @OA\Items(type="integer"), example={101,102}),
 *       @OA\Property(property="actions", type="array", @OA\Items(type="string"), example={"view","update"})
 *     )
 *   }
 * )
 */
class RolePermissionApi
{
    /**
     * @OA\Get(
     *   path="/api/v1/roles/{id}/permissions",
     *   summary="역할의 퍼미션 목록 조회",
     *   description="해당 역할에 현재 부여된 퍼미션 목록을 반환합니다.",
     *   tags={"RolePermission"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=3),
     *   @OA\Response(response=200, description="조회 성공",
     *     @OA\JsonContent(
     *       allOf={
     *         @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *         @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/PermissionList"))
     *       }
     *     )
     *   ),
     *   @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 list() {}

    /**
     * @OA\Post(
     *   path="/api/v1/roles/{id}/permissions",
     *   summary="역할에 퍼미션 부여",
     *   description="퍼미션 이름 배열 또는 메뉴ID+액션 조합으로 역할에 권한을 부여합니다.",
     *   tags={"RolePermission"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=3),
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/RolePermissionGrantRequest")),
     *   @OA\Response(response=200, description="부여 성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse")),
     *   @OA\Response(response=404, description="역할/퍼미션 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=422, 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 grant() {}

    /**
     * @OA\Delete(
     *   path="/api/v1/roles/{id}/permissions",
     *   summary="역할에서 퍼미션 회수",
     *   description="퍼미션 이름 배열 또는 메뉴ID+액션 조합으로 권한을 회수합니다.",
     *   tags={"RolePermission"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=3),
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/RolePermissionRevokeRequest")),
     *   @OA\Response(response=200, description="회수 성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse")),
     *   @OA\Response(response=404, description="역할/퍼미션 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=422, 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 revoke() {}

    /**
     * @OA\Put(
     *   path="/api/v1/roles/{id}/permissions/sync",
     *   summary="역할의 퍼미션 동기화(교체)",
     *   description="전달된 목록으로 역할의 권한을 완전히 교체합니다.",
     *   tags={"RolePermission"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=3),
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/RolePermissionSyncRequest")),
     *   @OA\Response(response=200, description="동기화 성공", @OA\JsonContent(ref="#/components/schemas/ApiResponse")),
     *   @OA\Response(response=404, description="역할/퍼미션 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
     *   @OA\Response(response=422, 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 sync() {}
}