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

<?php

namespace App\Swagger\v1;

/**
 * @OA\Tag(
 *   name="UserRole",
 *   description="사용자-역할 매핑(조회/부여/회수/동기화)"
 * )
 */

/**
 * @OA\Schema(
 *   schema="UserRoleGrantRequest",
 *   type="object",
 *   description="사용자에게 역할 부여. role_names 또는 role_ids 중 하나 사용.",
 *   oneOf={
 *     @OA\Schema(
 *       required={"role_names"},
 *
 *       @OA\Property(property="role_names", type="array", @OA\Items(type="string"), example={"menu-manager","readonly"})
 *     ),
 *
 *     @OA\Schema(
 *       required={"role_ids"},
 *
 *       @OA\Property(property="role_ids", type="array", @OA\Items(type="integer"), example={1,2})
 *     )
 *   }
 * )
 *
 * @OA\Schema(
 *   schema="UserRoleRevokeRequest",
 *   type="object",
 *   description="사용자로부터 역할 회수. role_names 또는 role_ids 중 하나 사용.",
 *   oneOf={
 *     @OA\Schema(
 *       required={"role_names"},
 *
 *       @OA\Property(property="role_names", type="array", @OA\Items(type="string"), example={"readonly"})
 *     ),
 *
 *     @OA\Schema(
 *       required={"role_ids"},
 *
 *       @OA\Property(property="role_ids", type="array", @OA\Items(type="integer"), example={2})
 *     )
 *   }
 * )
 *
 * @OA\Schema(
 *   schema="UserRoleSyncRequest",
 *   type="object",
 *   description="사용자의 역할을 전달된 목록으로 완전히 교체. role_names 또는 role_ids 중 하나 사용.",
 *   oneOf={
 *     @OA\Schema(
 *       required={"role_names"},
 *
 *       @OA\Property(property="role_names", type="array", @OA\Items(type="string"), example={"menu-manager"})
 *     ),
 *
 *     @OA\Schema(
 *       required={"role_ids"},
 *
 *       @OA\Property(property="role_ids", type="array", @OA\Items(type="integer"), example={1})
 *     )
 *   }
 * )
 */
class UserRoleApi
{
    /**
     * @OA\Get(
     *   path="/api/v1/users/{id}/roles",
     *   summary="사용자의 역할 목록 조회",
     *   description="해당 사용자에게 현재 부여된 역할 목록을 반환합니다.",
     *   tags={"UserRole"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
     *
     *   @OA\Response(
     *     response=200,
     *     description="조회 성공",
     *
     *     @OA\JsonContent(
     *       allOf={
     *
     *         @OA\Schema(ref="#/components/schemas/ApiResponse"),
     *         @OA\Schema(
     *
     *           @OA\Property(
     *             property="data",
     *             type="array",
     *
     *             @OA\Items(ref="#/components/schemas/RoleBrief")
     *           )
     *         )
     *       }
     *     )
     *   ),
     *
     *   @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 index() {}

    /**
     * @OA\Post(
     *   path="/api/v1/users/{id}/roles",
     *   summary="사용자에게 역할 부여",
     *   description="role_names 또는 role_ids로 여러 역할을 부여합니다.",
     *   tags={"UserRole"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
     *
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/UserRoleGrantRequest")),
     *
     *   @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/users/{id}/roles",
     *   summary="사용자의 역할 회수",
     *   description="role_names 또는 role_ids로 여러 역할을 회수합니다.",
     *   tags={"UserRole"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
     *
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/UserRoleRevokeRequest")),
     *
     *   @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/users/{id}/roles/sync",
     *   summary="사용자의 역할 동기화(교체)",
     *   description="전달된 목록으로 사용자의 역할을 완전히 교체합니다.",
     *   tags={"UserRole"},
     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
     *
     *   @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
     *
     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/UserRoleSyncRequest")),
     *
     *   @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() {}
}