SamProject/sam-api
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c637dd38ebd65cb2d80e98ab10bd2f4935282ac2
sam-api/app/Swagger/v1/RoleApi.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

287 lines
12 KiB
PHP
Raw Blame History

<?php
namespace App\Swagger\v1;
/**
* @OA\Tag(name="Role", description="역할 관리(목록/조회/등록/수정/삭제/통계/활성)")
*/
/**
* @OA\Schema(
* schema="Role",
* type="object",
* description="역할 상세",
* required={"id","name","guard_name"},
*
* @OA\Property(property="id", type="integer", example=3),
* @OA\Property(property="tenant_id", type="integer", example=1),
* @OA\Property(property="name", type="string", example="menu-manager"),
* @OA\Property(property="description", type="string", nullable=true, example="메뉴 관리 역할"),
* @OA\Property(property="guard_name", type="string", example="api"),
* @OA\Property(property="is_hidden", type="boolean", example=false),
* @OA\Property(property="permissions_count", type="integer", example=12),
* @OA\Property(property="users_count", type="integer", example=3),
* @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="RoleBrief",
* type="object",
* description="역할 요약",
* required={"id","name"},
*
* @OA\Property(property="id", type="integer", example=3),
* @OA\Property(property="name", type="string", example="readonly"),
* @OA\Property(property="description", type="string", nullable=true, example="읽기 전용"),
* @OA\Property(property="guard_name", type="string", example="api")
* )
*
* @OA\Schema(
* schema="RoleList",
* type="array",
*
* @OA\Items(ref="#/components/schemas/RoleBrief")
* )
*
* @OA\Schema(
* schema="RoleCreateRequest",
* type="object",
* required={"name"},
*
* @OA\Property(property="name", type="string", example="menu-manager", description="역할명(테넌트+가드 내 고유)"),
* @OA\Property(property="description", type="string", nullable=true, example="메뉴 관리 역할"),
* @OA\Property(property="is_hidden", type="boolean", example=false, description="숨김 여부")
* )
*
* @OA\Schema(
* schema="RoleUpdateRequest",
* type="object",
*
* @OA\Property(property="name", type="string", example="menu-admin"),
* @OA\Property(property="description", type="string", nullable=true, example="설명 변경"),
* @OA\Property(property="is_hidden", type="boolean", example=false)
* )
*
* @OA\Schema(
* schema="RoleStats",
* type="object",
* description="역할 통계",
*
* @OA\Property(property="total", type="integer", example=5),
* @OA\Property(property="visible", type="integer", example=3),
* @OA\Property(property="hidden", type="integer", example=2),
* @OA\Property(property="with_users", type="integer", example=4)
* )
*/
class RoleApi
{
/**
* @OA\Get(
* path="/api/v1/roles",
* summary="역할 목록 조회",
* description="테넌트 범위 내 역할 목록을 페이징으로 반환합니다. (q로 이름/설명 검색, is_hidden으로 필터)",
* tags={"Role"},
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
*
* @OA\Parameter(name="page", in="query", required=false, @OA\Schema(type="integer", example=1)),
* @OA\Parameter(name="size", in="query", required=false, @OA\Schema(type="integer", example=10)),
* @OA\Parameter(name="q", in="query", required=false, @OA\Schema(type="string", example="read")),
* @OA\Parameter(name="is_hidden", in="query", required=false, description="숨김 상태 필터", @OA\Schema(type="boolean", example=false)),
*
* @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="current_page", type="integer", example=1),
* @OA\Property(property="per_page", type="integer", example=10),
* @OA\Property(property="total", type="integer", example=2),
* @OA\Property(property="data", ref="#/components/schemas/RoleList")
* ))
* }
* )
* ),
*
* @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/roles",
* summary="역할 생성",
* description="새로운 역할을 생성합니다.",
* tags={"Role"},
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
*
* @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/RoleCreateRequest")),
*
* @OA\Response(response=200, description="생성 성공",
*
* @OA\JsonContent(
* allOf={
*
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
* @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Role"))
* }
* )
* ),
*
* @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 store() {}
/**
* @OA\Get(
* path="/api/v1/roles/{id}",
* summary="역할 단건 조회",
* description="ID로 역할 상세를 조회합니다.",
* tags={"Role"},
* 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/Role"))
* }
* )
* ),
*
* @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\Patch(
* path="/api/v1/roles/{id}",
* summary="역할 수정",
* description="기존 역할 정보를 부분 수정합니다.",
* tags={"Role"},
* 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/RoleUpdateRequest")),
*
* @OA\Response(response=200, description="수정 성공",
*
* @OA\JsonContent(
* allOf={
*
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
* @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/Role"))
* }
* )
* ),
*
* @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 update() {}
/**
* @OA\Delete(
* path="/api/v1/roles/{id}",
* summary="역할 삭제",
* description="지정한 역할을 삭제합니다.",
* tags={"Role"},
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
*
* @OA\Parameter(name="id", in="path", required=true, @OA\Schema(type="integer", example=3)),
*
* @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=403, description="권한 없음", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function destroy() {}
/**
* @OA\Get(
* path="/api/v1/roles/stats",
* summary="역할 통계 조회",
* description="테넌트 범위 내 역할 통계(전체/공개/숨김/사용자 보유)를 반환합니다.",
* tags={"Role"},
* 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/RoleStats"))
* }
* )
* ),
*
* @OA\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function stats() {}
/**
* @OA\Get(
* path="/api/v1/roles/active",
* summary="활성 역할 목록 (드롭다운용)",
* description="숨겨지지 않은 활성 역할 목록을 이름순으로 반환합니다. (id, name, description만 포함)",
* tags={"Role"},
* security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
*
* @OA\Response(response=200, description="목록 조회 성공",
*
* @OA\JsonContent(
* allOf={
*
* @OA\Schema(ref="#/components/schemas/ApiResponse"),
* @OA\Schema(@OA\Property(property="data", type="array",
*
* @OA\Items(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\Response(response=401, description="인증 실패", @OA\JsonContent(ref="#/components/schemas/ErrorResponse")),
* @OA\Response(response=500, description="서버 에러", @OA\JsonContent(ref="#/components/schemas/ErrorResponse"))
* )
*/
public function active() {}
}
Reference in New Issue View Git Blame Copy Permalink