feat(permission): add endpoint for retrieving all and single permission (#109)

This adds new endpoints to retrieve all permissions and a single
permission. The implementation enhances the system's capability for
managing permissions.

---------

Signed-off-by: Valentin Sickert <[email protected]>
Signed-off-by: Lapotor <[email protected]>

Author: Lapotor

.github/assets/swagger.yml

@@ -657,6 +657,111 @@ paths:
       security:
         - BearerAuth: []
 
+  /permissions:
+    get:
+      tags:
+        - Permission
+      summary: Retrieves all permissions
+      operationId: getPermissions
+      parameters:
+        - name: sort
+          in: query
+          schema:
+            type: string
+            enum:
+              - id
+              - id:asc
+              - id:desc
+              - name
+              - name:asc
+              - name:desc
+            default: id
+        - name: per_page
+          in: query
+          schema:
+            type: integer
+            default: 25
+            maximum: 50
+        - name: page
+          in: query
+          schema:
+            type: integer
+            default: 1
+            minimum: 0
+      responses:
+        "200":
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Permission"
+        "403":
+          description:
+            "Forbidden - The server understood the request, but is refusing\
+            \ to fulfill it."
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "500":
+          description:
+            "Internal Server Error - A generic error message, given when\
+            \ an unexpected condition was encountered and no more specific message\
+            \ is suitable."
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+      security:
+        - BearerAuth: []
+
+  /permissions/{id}:
+    get:
+      tags:
+        - Permission
+      summary: Retrieves a permission
+      operationId: getPermission
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        "200":
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Permission"
+        "403":
+          description:
+            "Forbidden - The server understood the request, but is refusing\
+            \ to fulfill it."
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "404":
+          description: Not Found - The server cannot find the requested resource.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "500":
+          description:
+            "Internal Server Error - A generic error message, given when\
+            \ an unexpected condition was encountered and no more specific message\
+            \ is suitable."
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+      security:
+        - BearerAuth: []
+
   /roles:
     get:
       tags:
@@ -1187,6 +1292,25 @@ components:
         role:
           type: integer
           nullable: true
+
+    Permission:
+      type: object
+      required:
+        - id
+        - name
+        - guard
+        - created_at
+        - updated_at
+      properties:
+        id:
+          type: integer
+          readOnly: true
+        name:
+          type: string
+          readOnly: true
+        guard:
+          type: string
+          readOnly: true
         created_at:
           type: string
           format: date-time
@@ -1195,6 +1319,7 @@ components:
           type: string
           format: date-time
           readOnly: true
+
     Role:
       required:
         - id

app/Http/Controllers/PermissionController.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Http\Responses\ApiSuccessResponse;
+use Illuminate\Http\Request;
+use Spatie\Permission\Models\Permission;
+
+class PermissionController extends Controller
+{
+
+    /**
+     * Display a paginated list of permissions.
+     *
+     * @param  \Illuminate\Http\Request  $request
+     * @return \Illuminate\Pagination\LengthAwarePaginator
+     */
+    public function index(Request $request): \Illuminate\Pagination\LengthAwarePaginator
+    {
+        $request->validate([
+            'sort' => 'string|in:id,id:asc,id:desc,name,name:asc,name:desc',
+            'per_page' => 'integer|between:1,50',
+        ]);
+
+        $perms = Permission::paginate($request->per_page ?? 25);
+
+        if ($request->sort) {
+            // Sort can be a string like 'id' or 'name:desc'
+            $sort = explode(':', $request->sort);
+            $perms = Permission::orderBy($sort[0], $sort[1] ?? 'asc')->paginate($request->per_page ?? 25);
+        } else {
+            $perms = Permission::orderBy('id')->paginate($request->per_page ?? 25);
+        }
+
+        return $perms;
+    }
+
+    /**
+         * Display the specified resource.
+         *
+         * @param \Spatie\Permission\Models\Permission $permission The permission to be displayed
+         * @return \App\Http\Responses\ApiSuccessResponse The success response containing the permission
+         */
+        public function show(Permission $permission): ApiSuccessResponse
+        {
+            return new ApiSuccessResponse($permission);
+        }
+}

routes/api.php

@@ -24,4 +24,5 @@
     require __DIR__ . '/api/v1/auth.php';
     require __DIR__ . '/api/v1/user.php';
     require __DIR__ . '/api/v1/role.php';
+    require __DIR__ . '/api/v1/permission.php';
 });

routes/api/v1/permission.php

@@ -0,0 +1,9 @@
+<?php
+
+use App\Http\Controllers\PermissionController;
+use Illuminate\Support\Facades\Route;
+
+Route::group(['middleware' => 'auth:sanctum'], function () {
+    Route::get('/permissions', [PermissionController::class, 'index'])->name('api.v1.permissions.index');
+    Route::get('/permissions/{permission}', [PermissionController::class, 'show'])->name('api.v1.permissions.show');
+});