Fix timestamp in API docs example response

[bookstack] / app / Http / Controllers / Api / RoleApiController.php

diff --git a/app/Http/Controllers/Api/RoleApiController.php b/app/Http/Controllers/Api/RoleApiController.php
index 11927982235dbd04cccefa012d4d231dbdaea690..6986c73f78d9befe3465b0fed3ee1b8b3a98b894 100644 (file)
--- a/app/Http/Controllers/Api/RoleApiController.php
+++ b/app/Http/Controllers/Api/RoleApiController.php
@@ -4,7 +4,6 @@ namespace BookStack\Http\Controllers\Api;
 
 use BookStack\Auth\Permissions\PermissionsRepo;
 use BookStack\Auth\Role;
-use BookStack\Exceptions\UserUpdateException;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\DB;
 
@@ -18,16 +17,16 @@ class RoleApiController extends ApiController
 
     protected $rules = [
         'create' => [
-            'display_name'  => ['required', 'min:3', 'max:180'],
-            'description'   => ['max:180'],
+            'display_name'  => ['required', 'string', 'min:3', 'max:180'],
+            'description'   => ['string', 'max:180'],
             'mfa_enforced'  => ['boolean'],
             'external_auth_id' => ['string'],
             'permissions'   => ['array'],
             'permissions.*' => ['string'],
         ],
         'update' => [
-            'display_name'  => ['min:3', 'max:180'],
-            'description'   => ['max:180'],
+            'display_name'  => ['string', 'min:3', 'max:180'],
+            'description'   => ['string', 'max:180'],
             'mfa_enforced'  => ['boolean'],
             'external_auth_id' => ['string'],
             'permissions'   => ['array'],
@@ -65,6 +64,7 @@ class RoleApiController extends ApiController
 
     /**
      * Create a new role in the system.
+     * Permissions should be provided as an array of permission name strings.
      * Requires permission to manage roles.
      */
     public function create(Request $request)
@@ -82,19 +82,24 @@ class RoleApiController extends ApiController
     }
 
     /**
-     * View the details of a single user.
+     * View the details of a single role.
+     * Provides the permissions and a high-level list of the users assigned.
      * Requires permission to manage roles.
      */
     public function read(string $id)
     {
-        $user = $this->permissionsRepo->getRoleById($id);
-        $this->singleFormatter($user);
+        $role = $this->permissionsRepo->getRoleById($id);
+        $this->singleFormatter($role);
 
-        return response()->json($user);
+        return response()->json($role);
     }
 
     /**
      * Update an existing role in the system.
+     * Permissions should be provided as an array of permission name strings.
+     * An empty "permissions" array would clear granted permissions.
+     * In many cases, where permissions are changed, you'll want to fetch the existing
+     * permissions and then modify before providing in your update request.
      * Requires permission to manage roles.
      */
     public function update(Request $request, string $id)
@@ -108,9 +113,7 @@ class RoleApiController extends ApiController
     }
 
     /**
-     * Delete a user from the system.
-     * Can optionally accept a user id via `migrate_ownership_id` to indicate
-     * who should be the new owner of their related content.
+     * Delete a role from the system.
      * Requires permission to manage roles.
      */
     public function delete(string $id)
@@ -127,7 +130,7 @@ class RoleApiController extends ApiController
     {
         $role->load('users:id,name,slug');
         $role->unsetRelation('permissions');
-        $role->setAttribute('permissions', $role->permissions()->pluck('name'));
+        $role->setAttribute('permissions', $role->permissions()->orderBy('name', 'asc')->pluck('name'));
         $role->makeVisible(['users', 'permissions']);
     }
 }