Added role API responses & requests

Also applied other slight tweaks and comment updates based upon manual
endpoint testing.

app/Auth/Role.php

@@ -31,6 +31,10 @@ class Role extends Model implements Loggable
 
     protected $hidden = ['pivot'];
 
+    protected $casts = [
+        'mfa_enforced' => 'boolean',
+    ];
+
     /**
      * The roles that belong to the role.
      */

app/Http/Controllers/Api/RoleApiController.php

@@ -17,16 +17,16 @@ class RoleApiController extends ApiController
 
     protected $rules = [
         'create' => [
-            'display_name'  => ['required', 'min:3', 'max:180'],
+            'display_name'  => ['required', 'string', 'min:3', 'max:180'],
-            'description'   => ['max:180'],
+            'description'   => ['string', 'max:180'],
             'mfa_enforced'  => ['boolean'],
             'external_auth_id' => ['string'],
             'permissions'   => ['array'],
             'permissions.*' => ['string'],
         ],
         'update' => [
-            'display_name'  => ['min:3', 'max:180'],
+            'display_name'  => ['string', 'min:3', 'max:180'],
-            'description'   => ['max:180'],
+            'description'   => ['string', 'max:180'],
             'mfa_enforced'  => ['boolean'],
             'external_auth_id' => ['string'],
             'permissions'   => ['array'],
@@ -64,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)
@@ -81,7 +82,8 @@ 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)
@@ -94,6 +96,10 @@ class RoleApiController extends ApiController
 
     /**
      * 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)
@@ -107,9 +113,7 @@ class RoleApiController extends ApiController
     }
 
     /**
-     * Delete a user from the system.
+     * Delete a role 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.
      * Requires permission to manage roles.
      */
     public function delete(string $id)

dev/api/requests/roles-create.json

@@ -0,0 +1,11 @@
+{
+  "display_name": "Book Maintainer",
+  "description": "People who maintain books",
+  "mfa_enforced": true,
+  "permissions": [
+    "book-view-all",
+    "book-update-all",
+    "book-delete-all",
+    "restrictions-manage-all"
+  ]
+}

dev/api/requests/roles-update.json

@@ -0,0 +1,14 @@
+{
+  "display_name": "Book & Shelf Maintainers",
+  "description": "All those who maintain books & shelves",
+  "mfa_enforced": false,
+  "permissions": [
+    "book-view-all",
+    "book-update-all",
+    "book-delete-all",
+    "bookshelf-view-all",
+    "bookshelf-update-all",
+    "bookshelf-delete-all",
+    "restrictions-manage-all"
+  ]
+}

dev/api/responses/roles-create.json

@@ -0,0 +1,15 @@
+{
+  "display_name": "Book Maintainer",
+  "description": "People who maintain books",
+  "mfa_enforced": true,
+  "updated_at": "2023-02-19T15:38:40.000000Z",
+  "created_at": "2023-02-19T15:38:40.000000Z",
+  "id": 26,
+  "permissions": [
+    "book-delete-all",
+    "book-update-all",
+    "book-view-all",
+    "restrictions-manage-all"
+  ],
+  "users": []
+}

dev/api/responses/roles-list.json

@@ -0,0 +1,41 @@
+{
+  "data": [
+    {
+      "id": 1,
+      "display_name": "Admin",
+      "description": "Administrator of the whole application",
+      "created_at": "2021-09-29T16:29:19.000000Z",
+      "updated_at": "2022-11-03T13:26:18.000000Z",
+      "system_name": "admin",
+      "external_auth_id": "wizards",
+      "mfa_enforced": true,
+      "users_count": 11,
+      "permissions_count": 54
+    },
+    {
+      "id": 2,
+      "display_name": "Editor",
+      "description": "User can edit Books, Chapters & Pages",
+      "created_at": "2021-09-29T16:29:19.000000Z",
+      "updated_at": "2022-12-01T02:32:57.000000Z",
+      "system_name": "",
+      "external_auth_id": "",
+      "mfa_enforced": false,
+      "users_count": 17,
+      "permissions_count": 49
+    },
+    {
+      "id": 3,
+      "display_name": "Public",
+      "description": "The role given to public visitors if allowed",
+      "created_at": "2021-09-29T16:29:19.000000Z",
+      "updated_at": "2022-09-02T12:32:12.000000Z",
+      "system_name": "public",
+      "external_auth_id": "",
+      "mfa_enforced": false,
+      "users_count": 1,
+      "permissions_count": 2
+    }
+  ],
+  "total": 3
+}

dev/api/responses/roles-read.json

@@ -0,0 +1,23 @@
+{
+  "id": 26,
+  "display_name": "Book Maintainer",
+  "description": "People who maintain books",
+  "created_at": "2023-02-19T15:38:40.000000Z",
+  "updated_at": "2023-02-19T15:38:40.000000Z",
+  "system_name": "",
+  "external_auth_id": "",
+  "mfa_enforced": true,
+  "permissions": [
+    "book-delete-all",
+    "book-update-all",
+    "book-view-all",
+    "restrictions-manage-all"
+  ],
+  "users": [
+    {
+      "id": 11,
+      "name": "Barry Scott",
+      "slug": "barry-scott"
+    }
+  ]
+}

dev/api/responses/roles-update.json

@@ -0,0 +1,26 @@
+{
+  "id": 26,
+  "display_name": "Book & Shelf Maintainers",
+  "description": "All those who maintain books & shelves",
+  "created_at": "2023-02-19T15:38:40.000000Z",
+  "updated_at": "2023-02-19T15:49:13.000000Z",
+  "system_name": "",
+  "external_auth_id": "",
+  "mfa_enforced": false,
+  "permissions": [
+    "book-delete-all",
+    "book-update-all",
+    "book-view-all",
+    "bookshelf-delete-all",
+    "bookshelf-update-all",
+    "bookshelf-view-all",
+    "restrictions-manage-all"
+  ],
+  "users": [
+    {
+      "id": 11,
+      "name": "Barry Scott",
+      "slug": "barry-scott"
+    }
+  ]
+}

routes/api.php

@@ -60,7 +60,7 @@ Route::delete('pages/{id}', [PageApiController::class, 'delete']);
 Route::get('pages/{id}/export/html', [PageExportApiController::class, 'exportHtml']);
 Route::get('pages/{id}/export/pdf', [PageExportApiController::class, 'exportPdf']);
 Route::get('pages/{id}/export/plaintext', [PageExportApiController::class, 'exportPlainText']);
-Route::get('pages/{id}/export/markdown', [PageExportApiController::class, 'exportMarkDown']);
+Route::get('pages/{id}/export/markdown', [PageExportApiController::class, 'exportMarkdown']);
 
 Route::get('search', [SearchApiController::class, 'all']);