recreate project

public/docs/openapi/role_permission_controller.yaml

@@ -0,0 +1,205 @@
+openapi: 3.0.3
+info:
+  title: Roles & Permissions API - Al Rahma Sunday School
+  version: 1.0.0
+  description: Manage roles, permissions, and user assignments.
+servers:
+  - url: https://your-domain.com/api/v1
+security:
+  - bearerAuth: []
+tags:
+  - name: Roles
+    description: Role definitions and assignments
+  - name: Permissions
+    description: Permission catalog and lookups
+  - name: Users
+    description: User search and role assignment helpers
+
+paths:
+  /roles:
+    get:
+      tags: [Roles]
+      summary: List all roles
+      responses:
+        "200":
+          description: Roles list
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RolesResponse'
+
+  /roles/{id}:
+    get:
+      tags: [Roles]
+      summary: Get role by ID
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: integer }
+      responses:
+        "200":
+          description: Single role
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RoleResponse'
+        "404":
+          description: Not found
+
+  /roles/{id}/permissions:
+    get:
+      tags: [Permissions]
+      summary: Permissions assigned to a role
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: integer }
+      responses:
+        "200":
+          description: Role permissions
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PermissionsResponse'
+
+  /permissions:
+    get:
+      tags: [Permissions]
+      summary: List all permissions
+      responses:
+        "200":
+          description: Permissions catalog
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PermissionsResponse'
+
+  /users:
+    get:
+      tags: [Users]
+      summary: List user summaries
+      parameters:
+        - in: query
+          name: q
+          schema: { type: string }
+      responses:
+        "200":
+          description: Users for assignment select lists
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UsersResponse'
+
+  /admins:
+    get:
+      tags: [Users]
+      summary: List admin users
+      responses:
+        "200":
+          description: Admins list
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UsersResponse'
+
+  /users/{id}/roles:
+    post:
+      tags: [Users]
+      summary: Assign roles to a user
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: integer }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignRolesRequest'
+      responses:
+        "200":
+          description: Roles assigned
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BasicSuccess'
+
+components:
+  schemas:
+    Role:
+      type: object
+      properties:
+        id: { type: integer }
+        name: { type: string }
+        description: { type: string, nullable: true }
+
+    Permission:
+      type: object
+      properties:
+        id: { type: integer }
+        name: { type: string }
+        description: { type: string, nullable: true }
+
+    UserSummary:
+      type: object
+      properties:
+        id: { type: integer }
+        firstname: { type: string }
+        lastname: { type: string }
+        email: { type: string }
+
+    RolesResponse:
+      type: object
+      properties:
+        status: { type: string }
+        message: { type: string }
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/Role'
+
+    RoleResponse:
+      type: object
+      properties:
+        status: { type: string }
+        message: { type: string }
+        data:
+          $ref: '#/components/schemas/Role'
+
+    PermissionsResponse:
+      type: object
+      properties:
+        status: { type: string }
+        message: { type: string }
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/Permission'
+
+    UsersResponse:
+      type: object
+      properties:
+        status: { type: string }
+        message: { type: string }
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/UserSummary'
+
+    AssignRolesRequest:
+      type: object
+      required: [role_ids]
+      properties:
+        role_ids:
+          type: array
+          items: { type: integer }
+
+    BasicSuccess:
+      type: object
+      properties:
+        status: { type: string }
+        message: { type: string }
+        data: {}