SamProject/sam-api
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c637dd38ebd65cb2d80e98ab10bd2f4935282ac2
sam-api/app/Swagger/v1/RolePermissionApi.php
김보곤 1dd9057540 refactor: [authz] 역할/권한 API 품질 개선 
- Validator::make를 FormRequest로 분리 (6개 생성)
- 하드코딩 한글 문자열을 i18n 키로 교체
- RoleMenuPermission 데드코드 제거
- Role 모델 SpatieRole 상속으로 일원화
- 권한 변경 후 캐시 무효화 추가 (AccessService::bumpVersion)
- 미문서화 8개 Swagger 엔드포인트 추가
- 역할/권한 라우트에 perm.map+permission 미들웨어 추가
2026-02-21 17:19:17 +09:00

393 lines
18 KiB
PHP
Raw Blame History

<?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"})
* )
* }
* )
*
* @OA\Schema(
* schema="PermissionMenuTree",
* type="object",
* description="권한 매트릭스용 메뉴 트리",
*
* @OA\Property(property="menus", type="array",
*
* @OA\Items(type="object",
*
* @OA\Property(property="id", type="integer", example=1),
* @OA\Property(property="parent_id", type="integer", nullable=true, example=null),
* @OA\Property(property="name", type="string", example="대시보드"),
* @OA\Property(property="url", type="string", nullable=true, example="/dashboard"),
* @OA\Property(property="icon", type="string", nullable=true, example="dashboard"),
* @OA\Property(property="sort_order", type="integer", example=1),
* @OA\Property(property="is_active", type="boolean", example=true),
* @OA\Property(property="depth", type="integer", example=0),
* @OA\Property(property="has_children", type="boolean", example=true)
* )
* ),
* @OA\Property(property="permission_types", type="array", @OA\Items(type="string"), example={"view","create","update","delete","approve","export","manage"})
* )
*
* @OA\Schema(
* schema="RolePermissionMatrix",
* type="object",
* description="역할의 권한 매트릭스",
*
* @OA\Property(property="role", type="object",
* @OA\Property(property="id", type="integer", example=1),
* @OA\Property(property="name", type="string", example="admin"),
* @OA\Property(property="description", type="string", nullable=true, example="관리자")
* ),
* @OA\Property(property="permission_types", type="array", @OA\Items(type="string"), example={"view","create","update","delete","approve","export","manage"}),
* @OA\Property(property="permissions", type="object", description="메뉴ID를 키로 한 권한 맵",
* example={"101": {"view": true, "create": true}, "102": {"view": true}},
* additionalProperties=true
* )
* )
*
* @OA\Schema(
* schema="RolePermissionToggleRequest",
* type="object",
* required={"menu_id","permission_type"},
*
* @OA\Property(property="menu_id", type="integer", example=101, description="메뉴 ID"),
* @OA\Property(property="permission_type", type="string", example="view", description="권한 유형 (view, create, update, delete, approve, export, manage)")
* )
*
* @OA\Schema(
* schema="RolePermissionToggleResponse",
* type="object",
*
* @OA\Property(property="menu_id", type="integer", example=101),
* @OA\Property(property="permission_type", type="string", example="view"),
* @OA\Property(property="granted", type="boolean", example=true, description="토글 후 권한 부여 상태")
* )
*/
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() {}
/**
* @OA\Get(
* path="/api/v1/role-permissions/menus",
* summary="권한 매트릭스용 메뉴 트리 조회",
* description="활성 메뉴를 플랫 배열(depth 포함)로 반환하고, 사용 가능한 권한 유형 목록을 함께 반환합니다.",
* tags={"RolePermission"},
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
*
* @OA\Response(response=200, description="조회 성공",
*
* @OA\JsonContent(
* allOf={
*
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
* @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/PermissionMenuTree"))
* }
* )
* ),
*
* @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function menus() {}
/**
* @OA\Get(
* path="/api/v1/roles/{id}/permissions/matrix",
* summary="역할의 권한 매트릭스 조회",
* description="해당 역할에 부여된 메뉴별 권한 매트릭스를 반환합니다.",
* tags={"RolePermission"},
* 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", ref="#/components/schemas/RolePermissionMatrix"))
* }
* )
* ),
*
* @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=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function matrix() {}
/**
* @OA\Post(
* path="/api/v1/roles/{id}/permissions/toggle",
* summary="특정 메뉴의 특정 권한 토글",
* description="지정한 메뉴+권한 유형의 부여 상태를 반전합니다. 하위 메뉴에 재귀적으로 전파합니다.",
* tags={"RolePermission"},
* 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/RolePermissionToggleRequest")),
*
* @OA\Response(response=200, description="토글 성공",
*
* @OA\JsonContent(
* allOf={
*
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
* @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/RolePermissionToggleResponse"))
* }
* )
* ),
*
* @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=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function toggle() {}
/**
* @OA\Post(
* path="/api/v1/roles/{id}/permissions/allow-all",
* summary="모든 권한 허용",
* description="해당 역할에 모든 활성 메뉴의 모든 권한 유형을 일괄 부여합니다.",
* tags={"RolePermission"},
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
*
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
*
* @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=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function allowAll() {}
/**
* @OA\Post(
* path="/api/v1/roles/{id}/permissions/deny-all",
* summary="모든 권한 거부",
* description="해당 역할의 모든 메뉴 권한을 일괄 제거합니다.",
* tags={"RolePermission"},
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
*
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
*
* @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=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function denyAll() {}
/**
* @OA\Post(
* path="/api/v1/roles/{id}/permissions/reset",
* summary="기본 권한으로 초기화 (view만 허용)",
* description="해당 역할의 모든 권한을 제거한 후, 모든 활성 메뉴에 view 권한만 부여합니다.",
* tags={"RolePermission"},
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
*
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer"), example=1),
*
* @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=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function reset() {}
}
Reference in New Issue View Git Blame Copy Permalink