fix: Swagger 경로 파라미터 라우트 일치 수정

- ItemsBomApi: {code} → {id} (10개 경로)
- BomCalculationApi: snake_case → camelCase 파라미터
- PermissionApi: {id} → 구체적 파라미터명 (dept_id, role_id, user_id)
- FieldProfileApi: opt-groups → settings/options, 중복 Fields 엔드포인트 제거

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

app/Swagger/v1/BomCalculationApi.php

@@ -222,14 +222,14 @@ class BomCalculationApi
 {
     /**
      * @OA\Get(
-     *   path="/api/v1/design/models/{model_id}/estimate-parameters",
+     *   path="/api/v1/design/models/{modelId}/estimate-parameters",
      *   summary="견적 파라미터 조회",
      *   description="특정 모델의 견적 시 필요한 입력 파라미터 스키마를 조회합니다. BOM에 정의된 조건만 동적으로 추출하여 반환합니다.",
      *   tags={"BOM Calculation"},
      *   security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
      *
      *   @OA\Parameter(
-     *     name="model_id",
+     *     name="modelId",
      *     in="path",
      *     required=true,
      *     description="모델 ID",
@@ -265,14 +265,14 @@ public function getEstimateParameters() {}
 
     /**
      * @OA\Post(
-     *   path="/api/v1/design/bom-templates/{bom_template_id}/calculate-bom",
+     *   path="/api/v1/design/bom-templates/{bomTemplateId}/calculate-bom",
      *   summary="BOM 계산 실행",
      *   description="입력된 파라미터를 기반으로 BOM 수량을 동적으로 계산합니다. 업체별 산출식을 적용하여 실시간 견적을 생성합니다.",
      *   tags={"BOM Calculation"},
      *   security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
      *
      *   @OA\Parameter(
-     *     name="bom_template_id",
+     *     name="bomTemplateId",
      *     in="path",
      *     required=true,
      *     description="BOM 템플릿 ID",
@@ -306,14 +306,14 @@ public function calculateBom() {}
 
     /**
      * @OA\Get(
-     *   path="/api/v1/design/companies/{company_name}/formulas",
+     *   path="/api/v1/design/companies/{companyName}/formulas",
      *   summary="업체별 산출식 목록 조회",
      *   description="특정 업체의 등록된 산출식 목록을 조회합니다.",
      *   tags={"BOM Calculation"},
      *   security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
      *
      *   @OA\Parameter(
-     *     name="company_name",
+     *     name="companyName",
      *     in="path",
      *     required=true,
      *     description="업체명",
@@ -340,14 +340,14 @@ public function getCompanyFormulas() {}
 
     /**
      * @OA\Post(
-     *   path="/api/v1/design/companies/{company_name}/formulas/{formula_type}",
+     *   path="/api/v1/design/companies/{companyName}/formulas/{formulaType}",
      *   summary="업체별 산출식 등록/수정",
      *   description="특정 업체의 산출식을 등록하거나 수정합니다. 기존 산출식이 있으면 새 버전으로 업데이트됩니다.",
      *   tags={"BOM Calculation"},
      *   security={{"ApiKeyAuth": {}}, {"BearerAuth": {}}},
      *
      *   @OA\Parameter(
-     *     name="company_name",
+     *     name="companyName",
      *     in="path",
      *     required=true,
      *     description="업체명",
@@ -356,7 +356,7 @@ public function getCompanyFormulas() {}
      *   ),
      *
      *   @OA\Parameter(
-     *     name="formula_type",
+     *     name="formulaType",
      *     in="path",
      *     required=true,
      *     description="산출식 타입",

app/Swagger/v1/FieldProfileApi.php

@@ -7,77 +7,12 @@
 /**
  * 전역 태그 선언
  *
- * @OA\Tag(name="Tenant.Fields", description="테넌트별 필드 구동(효과값 조회/설정)")
  * @OA\Tag(name="Tenant.Option Groups", description="테넌트 관리형 옵션 그룹")
  * @OA\Tag(name="Tenant.Option Values", description="옵션 그룹의 항목(값) 관리")
  * @OA\Tag(name="Tenant.Profiles", description="테넌트별 회원 프로필 조회/수정")
  */
 class FieldProfileApi
 {
-    /**
-     * Fields(효과값/설정) 스키마
-     *
-     * @OA\Schema(
-     *   schema="FieldEffective",
-     *   type="object",
-     *   description="전역정의 + 테넌트설정이 merge된 필드 효과값",
-     *   required={"field_key","label","data_type","input_type","enabled"},
-     *
-     *   @OA\Property(property="field_key", type="string", example="position"),
-     *   @OA\Property(property="label", type="string", example="직급"),
-     *   @OA\Property(property="data_type", type="string", example="string"),
-     *   @OA\Property(property="input_type", type="string", example="select"),
-     *   @OA\Property(property="option_source", type="string", nullable=true, example="tenant_list"),
-     *   @OA\Property(property="option_payload", type="object", nullable=true),
-     *   @OA\Property(property="storage_area", type="string", example="tenant_profile"),
-     *   @OA\Property(property="storage_key", type="string", example="position_key"),
-     *   @OA\Property(property="is_core", type="boolean", example=false),
-     *   @OA\Property(property="enabled", type="boolean", example=true),
-     *   @OA\Property(property="required", type="boolean", example=false),
-     *   @OA\Property(property="sort_order", type="integer", example=10),
-     *   @OA\Property(property="option_group_id", type="integer", nullable=true, example=5),
-     *   @OA\Property(property="code_group", type="string", nullable=true, example="employment_type")
-     * )
-     *
-     * @OA\Schema(
-     *   schema="FieldSettingUpdateRequest",
-     *   type="object",
-     *
-     *   @OA\Property(property="enabled", type="boolean", example=true),
-     *   @OA\Property(property="required", type="boolean", example=false),
-     *   @OA\Property(property="sort_order", type="integer", example=20),
-     *   @OA\Property(property="option_group_id", type="integer", nullable=true, example=5),
-     *   @OA\Property(property="code_group", type="string", nullable=true, example="department")
-     * )
-     *
-     * @OA\Schema(
-     *   schema="FieldSettingBulkItem",
-     *   type="object",
-     *   required={"field_key"},
-     *
-     *   @OA\Property(property="field_key", type="string", example="position"),
-     *   @OA\Property(property="enabled", type="boolean", example=true),
-     *   @OA\Property(property="required", type="boolean", example=false),
-     *   @OA\Property(property="sort_order", type="integer", example=10),
-     *   @OA\Property(property="option_group_id", type="integer", nullable=true, example=5),
-     *   @OA\Property(property="code_group", type="string", nullable=true, example="employment_type")
-     * )
-     *
-     * @OA\Schema(
-     *   schema="FieldSettingBulkRequest",
-     *   type="object",
-     *   required={"items"},
-     *
-     *   @OA\Property(
-     *     property="items",
-     *     type="array",
-     *
-     *     @OA\Items(ref="#/components/schemas/FieldSettingBulkItem")
-     *   )
-     * )
-     */
-    public function _fieldSchemasNoop() {}
-
     /**
      * Option Group/Value 스키마
      *
@@ -223,100 +158,7 @@ public function _profileSchemasNoop() {}
 
     /**
      * @OA\Get(
-     *   path="/api/v1/fields",
+     *   path="/api/v1/settings/options",
-     *   summary="효과값 필드 목록",
-     *   description="전역 필드 정의와 테넌트 설정을 병합한, 실제 화면 노출용(Enabled) 필드 목록을 반환합니다.",
-     *   tags={"Tenant.Fields"},
-     *   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(ref="#/components/schemas/FieldEffective")
-     *       ))
-     *     })
-     *   ),
-     *
-     *   @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 fieldsIndex() {}
-
-    /**
-     * @OA\Put(
-     *   path="/api/v1/fields/bulk",
-     *   summary="필드 설정 대량 저장",
-     *   description="여러 필드에 대해 enabled/required/sort_order/option_group_id/code_group 설정을 한번에 저장합니다.",
-     *   tags={"Tenant.Fields"},
-     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
-     *
-     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/FieldSettingBulkRequest")),
-     *
-     *   @OA\Response(
-     *     response=200,
-     *     description="저장 성공",
-     *
-     *     @OA\JsonContent(allOf={
-     *
-     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
-     *       @OA\Schema(@OA\Property(property="data", type="object", example={"updated":true}))
-     *     })
-     *   ),
-     *
-     *   @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 fieldsBulk() {}
-
-    /**
-     * @OA\Patch(
-     *   path="/api/v1/fields/{key}",
-     *   summary="필드 설정 단건 수정",
-     *   description="특정 field_key에 대한 테넌트 설정을 수정합니다.",
-     *   tags={"Tenant.Fields"},
-     *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
-     *
-     *   @OA\Parameter(
-     *     name="key", in="path", required=true,
-     *     description="수정할 필드 키", @OA\Schema(type="string", example="position")
-     *   ),
-     *
-     *   @OA\RequestBody(required=true, @OA\JsonContent(ref="#/components/schemas/FieldSettingUpdateRequest")),
-     *
-     *   @OA\Response(
-     *     response=200,
-     *     description="수정 성공",
-     *
-     *     @OA\JsonContent(allOf={
-     *
-     *       @OA\Schema(ref="#/components/schemas/ApiResponse"),
-     *       @OA\Schema(@OA\Property(property="data", ref="#/components/schemas/FieldEffective"))
-     *     })
-     *   ),
-     *
-     *   @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 fieldsUpdateOne() {}
-
-    /**
-     * @OA\Get(
-     *   path="/api/v1/opt-groups",
      *   summary="옵션 그룹 목록",
      *   description="해당 테넌트의 옵션 그룹 목록을 페이징으로 반환합니다.",
      *   tags={"Tenant.Option Groups"},
@@ -349,7 +191,7 @@ public function optGroupsIndex() {}
 
     /**
      * @OA\Post(
-     *   path="/api/v1/opt-groups",
+     *   path="/api/v1/settings/options",
      *   summary="옵션 그룹 생성",
      *   description="옵션 그룹을 생성합니다.",
      *   tags={"Tenant.Option Groups"},
@@ -371,7 +213,7 @@ public function optGroupsStore() {}
 
     /**
      * @OA\Get(
-     *   path="/api/v1/opt-groups/{id}",
+     *   path="/api/v1/settings/options/{id}",
      *   summary="옵션 그룹 단건 조회",
      *   tags={"Tenant.Option Groups"},
      *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
@@ -392,7 +234,7 @@ public function optGroupsShow() {}
 
     /**
      * @OA\Patch(
-     *   path="/api/v1/opt-groups/{id}",
+     *   path="/api/v1/settings/options/{id}",
      *   summary="옵션 그룹 수정",
      *   tags={"Tenant.Option Groups"},
      *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
@@ -415,7 +257,7 @@ public function optGroupsUpdate() {}
 
     /**
      * @OA\Delete(
-     *   path="/api/v1/opt-groups/{id}",
+     *   path="/api/v1/settings/options/{id}",
      *   summary="옵션 그룹 삭제",
      *   tags={"Tenant.Option Groups"},
      *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
@@ -436,7 +278,7 @@ public function optGroupsDestroy() {}
 
     /**
      * @OA\Get(
-     *   path="/api/v1/opt-groups/{gid}/values",
+     *   path="/api/v1/settings/options/{gid}/values",
      *   summary="옵션 값 목록",
      *   tags={"Tenant.Option Values"},
      *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
@@ -458,7 +300,7 @@ public function optionValuesIndex() {}
 
     /**
      * @OA\Post(
-     *   path="/api/v1/opt-groups/{gid}/values",
+     *   path="/api/v1/settings/options/{gid}/values",
      *   summary="옵션 값 생성",
      *   tags={"Tenant.Option Values"},
      *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
@@ -481,7 +323,7 @@ public function optionValuesStore() {}
 
     /**
      * @OA\Get(
-     *   path="/api/v1/opt-groups/{gid}/values/{id}",
+     *   path="/api/v1/settings/options/{gid}/values/{id}",
      *   summary="옵션 값 단건 조회",
      *   tags={"Tenant.Option Values"},
      *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
@@ -503,7 +345,7 @@ public function optionValuesShow() {}
 
     /**
      * @OA\Patch(
-     *   path="/api/v1/opt-groups/{gid}/values/{id}",
+     *   path="/api/v1/settings/options/{gid}/values/{id}",
      *   summary="옵션 값 수정",
      *   tags={"Tenant.Option Values"},
      *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
@@ -527,7 +369,7 @@ public function optionValuesUpdate() {}
 
     /**
      * @OA\Delete(
-     *   path="/api/v1/opt-groups/{gid}/values/{id}",
+     *   path="/api/v1/settings/options/{gid}/values/{id}",
      *   summary="옵션 값 삭제",
      *   tags={"Tenant.Option Values"},
      *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
@@ -549,7 +391,7 @@ public function optionValuesDestroy() {}
 
     /**
      * @OA\Patch(
-     *   path="/api/v1/opt-groups/{gid}/values/reorder",
+     *   path="/api/v1/settings/options/{gid}/values/reorder",
      *   summary="옵션 값 정렬 순서 일괄 변경",
      *   tags={"Tenant.Option Values"},
      *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},

app/Swagger/v1/ItemsBomApi.php

@@ -3,7 +3,7 @@
 namespace App\Swagger\v1;
 
 /**
- * @OA\Tag(name="Items BOM", description="품목 BOM 관리 (Code 기반)")
+ * @OA\Tag(name="Items BOM", description="품목 BOM 관리")
  *
  * @OA\Schema(
  *   schema="BOMLine",
@@ -81,12 +81,12 @@ class ItemsBomApi
 {
     /**
      * @OA\Get(
-     *   path="/api/v1/items/{code}/bom",
+     *   path="/api/v1/items/{id}/bom",
      *   tags={"Items BOM"},
      *   summary="BOM 목록 조회 (flat list)",
      *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
      *
-     *   @OA\Parameter(name="code", in="path", required=true, @OA\Schema(type="string"), example="P-001"),
+     *   @OA\Parameter(name="id", in="path", required=true, description="품목 ID", @OA\Schema(type="integer"), example=1),
      *
      *   @OA\Response(
      *     response=200,
@@ -111,12 +111,12 @@ public function index() {}
 
     /**
      * @OA\Get(
-     *   path="/api/v1/items/{code}/bom/tree",
+     *   path="/api/v1/items/{id}/bom/tree",
      *   tags={"Items BOM"},
      *   summary="BOM 트리 구조 조회 (계층적)",
      *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
      *
-     *   @OA\Parameter(name="code", in="path", required=true, @OA\Schema(type="string"), example="P-001"),
+     *   @OA\Parameter(name="id", in="path", required=true, description="품목 ID", @OA\Schema(type="integer"), example=1),
      *   @OA\Parameter(name="depth", in="query", @OA\Schema(type="integer"), example=10, description="최대 깊이 (기본값: 10)"),
      *
      *   @OA\Response(
@@ -137,12 +137,12 @@ public function tree() {}
 
     /**
      * @OA\Post(
-     *   path="/api/v1/items/{code}/bom",
+     *   path="/api/v1/items/{id}/bom",
      *   tags={"Items BOM"},
      *   summary="BOM 라인 추가 (bulk upsert)",
      *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
      *
-     *   @OA\Parameter(name="code", in="path", required=true, @OA\Schema(type="string"), example="P-001"),
+     *   @OA\Parameter(name="id", in="path", required=true, description="품목 ID", @OA\Schema(type="integer"), example=1),
      *
      *   @OA\RequestBody(
      *     required=true,
@@ -173,12 +173,12 @@ public function store() {}
 
     /**
      * @OA\Put(
-     *   path="/api/v1/items/{code}/bom/{lineId}",
+     *   path="/api/v1/items/{id}/bom/{lineId}",
      *   tags={"Items BOM"},
      *   summary="BOM 라인 수정",
      *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
      *
-     *   @OA\Parameter(name="code", in="path", required=true, @OA\Schema(type="string"), example="P-001"),
+     *   @OA\Parameter(name="id", in="path", required=true, description="품목 ID", @OA\Schema(type="integer"), example=1),
      *   @OA\Parameter(name="lineId", in="path", required=true, @OA\Schema(type="integer"), example=1),
      *
      *   @OA\RequestBody(
@@ -205,12 +205,12 @@ public function update() {}
 
     /**
      * @OA\Delete(
-     *   path="/api/v1/items/{code}/bom/{lineId}",
+     *   path="/api/v1/items/{id}/bom/{lineId}",
      *   tags={"Items BOM"},
      *   summary="BOM 라인 삭제",
      *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
      *
-     *   @OA\Parameter(name="code", in="path", required=true, @OA\Schema(type="string"), example="P-001"),
+     *   @OA\Parameter(name="id", in="path", required=true, description="품목 ID", @OA\Schema(type="integer"), example=1),
      *   @OA\Parameter(name="lineId", in="path", required=true, @OA\Schema(type="integer"), example=1),
      *
      *   @OA\Response(
@@ -231,12 +231,12 @@ public function destroy() {}
 
     /**
      * @OA\Get(
-     *   path="/api/v1/items/{code}/bom/summary",
+     *   path="/api/v1/items/{id}/bom/summary",
      *   tags={"Items BOM"},
      *   summary="BOM 요약 정보",
      *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
      *
-     *   @OA\Parameter(name="code", in="path", required=true, @OA\Schema(type="string"), example="P-001"),
+     *   @OA\Parameter(name="id", in="path", required=true, description="품목 ID", @OA\Schema(type="integer"), example=1),
      *
      *   @OA\Response(
      *     response=200,
@@ -263,12 +263,12 @@ public function summary() {}
 
     /**
      * @OA\Get(
-     *   path="/api/v1/items/{code}/bom/validate",
+     *   path="/api/v1/items/{id}/bom/validate",
      *   tags={"Items BOM"},
      *   summary="BOM 유효성 검사",
      *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
      *
-     *   @OA\Parameter(name="code", in="path", required=true, @OA\Schema(type="string"), example="P-001"),
+     *   @OA\Parameter(name="id", in="path", required=true, description="품목 ID", @OA\Schema(type="integer"), example=1),
      *
      *   @OA\Response(
      *     response=200,
@@ -303,12 +303,12 @@ public function validate() {}
 
     /**
      * @OA\Post(
-     *   path="/api/v1/items/{code}/bom/replace",
+     *   path="/api/v1/items/{id}/bom/replace",
      *   tags={"Items BOM"},
      *   summary="BOM 전체 교체 (기존 삭제 후 재등록)",
      *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
      *
-     *   @OA\Parameter(name="code", in="path", required=true, @OA\Schema(type="string"), example="P-001"),
+     *   @OA\Parameter(name="id", in="path", required=true, description="품목 ID", @OA\Schema(type="integer"), example=1),
      *
      *   @OA\RequestBody(
      *     required=true,
@@ -368,12 +368,12 @@ public function replace() {}
 
     /**
      * @OA\Post(
-     *   path="/api/v1/items/{code}/bom/reorder",
+     *   path="/api/v1/items/{id}/bom/reorder",
      *   tags={"Items BOM"},
      *   summary="BOM 정렬 변경",
      *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
      *
-     *   @OA\Parameter(name="code", in="path", required=true, @OA\Schema(type="string"), example="P-001"),
+     *   @OA\Parameter(name="id", in="path", required=true, description="품목 ID", @OA\Schema(type="integer"), example=1),
      *
      *   @OA\RequestBody(
      *     required=true,
@@ -414,12 +414,12 @@ public function reorder() {}
 
     /**
      * @OA\Get(
-     *   path="/api/v1/items/{code}/bom/categories",
+     *   path="/api/v1/items/{id}/bom/categories",
      *   tags={"Items BOM"},
      *   summary="BOM에서 사용 중인 카테고리 목록",
      *   security={{"ApiKeyAuth": {}, "BearerAuth": {}}},
      *
-     *   @OA\Parameter(name="code", in="path", required=true, @OA\Schema(type="string"), example="P-001"),
+     *   @OA\Parameter(name="id", in="path", required=true, description="품목 ID", @OA\Schema(type="integer"), example=1),
      *
      *   @OA\Response(
      *     response=200,

app/Swagger/v1/PermissionApi.php

@@ -76,13 +76,13 @@ class PermissionApi
 {
     /**
      * @OA\Get(
-     *   path="/api/v1/permissions/departments/{id}/menu-matrix",
+     *   path="/api/v1/permissions/departments/{dept_id}/menu-matrix",
      *   summary="부서 메뉴 권한 매트릭스",
      *   description="부서 기준으로 메뉴 트리 및 액션별 권한 상태(allow/deny/none)를 반환합니다.",
      *   tags={"Permission"},
      *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
      *
-     *   @OA\Parameter(name="id", in="path", required=true, description="부서 ID", @OA\Schema(type="integer", example=1)),
+     *   @OA\Parameter(name="dept_id", in="path", required=true, description="부서 ID", @OA\Schema(type="integer", example=1)),
      *
      *   @OA\Response(
      *     response=200,
@@ -107,13 +107,13 @@ public function deptMenuMatrix() {}
 
     /**
      * @OA\Get(
-     *   path="/api/v1/permissions/roles/{id}/menu-matrix",
+     *   path="/api/v1/permissions/roles/{role_id}/menu-matrix",
      *   summary="역할 메뉴 권한 매트릭스",
      *   description="스파티 기본 Role 기준으로 메뉴 트리 및 액션별 권한 상태(allow/deny/none)를 반환합니다.",
      *   tags={"Permission"},
      *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
      *
-     *   @OA\Parameter(name="id", in="path", required=true, description="역할 ID", @OA\Schema(type="integer", example=3)),
+     *   @OA\Parameter(name="role_id", in="path", required=true, description="역할 ID", @OA\Schema(type="integer", example=3)),
      *
      *   @OA\Response(
      *     response=200,
@@ -138,13 +138,13 @@ public function roleMenuMatrix() {}
 
     /**
      * @OA\Get(
-     *   path="/api/v1/permissions/users/{id}/menu-matrix",
+     *   path="/api/v1/permissions/users/{user_id}/menu-matrix",
      *   summary="사용자 메뉴 권한 매트릭스",
      *   description="사용자 기준으로 메뉴 트리 및 액션별 권한 상태(allow/deny/none)를 반환합니다.",
      *   tags={"Permission"},
      *   security={{"ApiKeyAuth": {}},{"BearerAuth": {}}},
      *
-     *   @OA\Parameter(name="id", in="path", required=true, description="사용자 ID", @OA\Schema(type="integer", example=12)),
+     *   @OA\Parameter(name="user_id", in="path", required=true, description="사용자 ID", @OA\Schema(type="integer", example=12)),
      *
      *   @OA\Response(
      *     response=200,