From: Dan Brown <redacted>
Date: Fri, 4 Feb 2022 00:44:56 +0000 (+0000)
Subject: Added user API examples
X-Git-Tag: v22.02~1^2~18^2~1
X-Git-Url: http://source.bookstackapp.com/bookstack/commitdiff_plain/46e6e239dc644b6949e6609c27339c62a84bc711

Added user API examples
---

diff --git a/app/Auth/User.php b/app/Auth/User.php
index c2b241381..b7f88b590 100644
--- a/app/Auth/User.php
+++ b/app/Auth/User.php
@@ -72,7 +72,7 @@ class User extends Model implements AuthenticatableContract, CanResetPasswordCon
      */
     protected $hidden = [
         'password', 'remember_token', 'system_name', 'email_confirmed', 'external_auth_id', 'email',
-        'created_at', 'updated_at', 'image_id', 'roles', 'avatar',
+        'created_at', 'updated_at', 'image_id', 'roles', 'avatar', 'user_id',
     ];
 
     /**
diff --git a/app/Http/Controllers/Api/UserApiController.php b/app/Http/Controllers/Api/UserApiController.php
index cd97dead1..aa2a2481c 100644
--- a/app/Http/Controllers/Api/UserApiController.php
+++ b/app/Http/Controllers/Api/UserApiController.php
@@ -81,6 +81,7 @@ class UserApiController extends ApiController
 
     /**
      * Create a new user in the system.
+     * Requires permission to manage users.
      */
     public function create(Request $request)
     {
@@ -111,6 +112,7 @@ class UserApiController extends ApiController
 
     /**
      * Update an existing user in the system.
+     * Requires permission to manage users.
      * @throws UserUpdateException
      */
     public function update(Request $request, string $id)
diff --git a/dev/api/requests/users-create.json b/dev/api/requests/users-create.json
new file mode 100644
index 000000000..ccc43d9e4
--- /dev/null
+++ b/dev/api/requests/users-create.json
@@ -0,0 +1,7 @@
+{
+  "name": "Dan Brown",
+  "email": "dannyb@example.com",
+  "roles": [1],
+  "language": "fr",
+  "send_invite": true
+}
\ No newline at end of file
diff --git a/dev/api/requests/users-update.json b/dev/api/requests/users-update.json
new file mode 100644
index 000000000..d7787ed1a
--- /dev/null
+++ b/dev/api/requests/users-update.json
@@ -0,0 +1,7 @@
+{
+  "name": "Dan Spaggleforth",
+  "email": "dspaggles@example.com",
+  "roles": [2],
+  "language": "de",
+  "password": "hunter2000"
+}
\ No newline at end of file
diff --git a/dev/api/responses/users-create.json b/dev/api/responses/users-create.json
new file mode 100644
index 000000000..509d88941
--- /dev/null
+++ b/dev/api/responses/users-create.json
@@ -0,0 +1,19 @@
+{
+  "id": 1,
+  "name": "Dan Brown",
+  "email": "dannyb@example.com",
+  "created_at": "2022-02-03T16:27:55.000000Z",
+  "updated_at": "2022-02-03T16:27:55.000000Z",
+  "external_auth_id": "abc123456",
+  "slug": "dan-brown",
+  "last_activity_at": "2022-02-03T16:27:55.000000Z",
+  "profile_url": "https://docs.example.com/user/dan-brown",
+  "edit_url": "https://docs.example.com/settings/users/1",
+  "avatar_url": "https://docs.example.com/uploads/images/user/2021-10/thumbs-50-50/profile-2021.jpg",
+  "roles": [
+    {
+      "id": 1,
+      "display_name": "Admin"
+    }
+  ]
+}
\ No newline at end of file
diff --git a/dev/api/responses/users-list.json b/dev/api/responses/users-list.json
new file mode 100644
index 000000000..e070ee6a6
--- /dev/null
+++ b/dev/api/responses/users-list.json
@@ -0,0 +1,33 @@
+{
+  "data": [
+    {
+      "id": 1,
+      "name": "Dan Brown",
+      "email": "dannyb@example.com",
+      "created_at": "2022-02-03T16:27:55.000000Z",
+      "updated_at": "2022-02-03T16:27:55.000000Z",
+      "external_auth_id": "abc123456",
+      "slug": "dan-brown",
+      "user_id": 1,
+      "last_activity_at": "2022-02-03T16:27:55.000000Z",
+      "profile_url": "https://docs.example.com/user/dan-brown",
+      "edit_url": "https://docs.example.com/settings/users/1",
+      "avatar_url": "https://docs.example.com/uploads/images/user/2021-10/thumbs-50-50/profile-2021.jpg"
+    },
+    {
+      "id": 2,
+      "name": "Benny",
+      "email": "benny@example.com",
+      "created_at": "2022-01-31T20:39:24.000000Z",
+      "updated_at": "2021-11-18T17:10:58.000000Z",
+      "external_auth_id": "",
+      "slug": "benny",
+      "user_id": 2,
+      "last_activity_at": "2022-01-31T20:39:24.000000Z",
+      "profile_url": "https://docs.example.com/user/benny",
+      "edit_url": "https://docs.example.com/settings/users/2",
+      "avatar_url": "https://docs.example.com/uploads/images/user/2021-11/thumbs-50-50/guest.jpg"
+    }
+  ],
+  "total": 28
+}
\ No newline at end of file
diff --git a/dev/api/responses/users-read.json b/dev/api/responses/users-read.json
new file mode 100644
index 000000000..509d88941
--- /dev/null
+++ b/dev/api/responses/users-read.json
@@ -0,0 +1,19 @@
+{
+  "id": 1,
+  "name": "Dan Brown",
+  "email": "dannyb@example.com",
+  "created_at": "2022-02-03T16:27:55.000000Z",
+  "updated_at": "2022-02-03T16:27:55.000000Z",
+  "external_auth_id": "abc123456",
+  "slug": "dan-brown",
+  "last_activity_at": "2022-02-03T16:27:55.000000Z",
+  "profile_url": "https://docs.example.com/user/dan-brown",
+  "edit_url": "https://docs.example.com/settings/users/1",
+  "avatar_url": "https://docs.example.com/uploads/images/user/2021-10/thumbs-50-50/profile-2021.jpg",
+  "roles": [
+    {
+      "id": 1,
+      "display_name": "Admin"
+    }
+  ]
+}
\ No newline at end of file
diff --git a/dev/api/responses/users-update.json b/dev/api/responses/users-update.json
new file mode 100644
index 000000000..611e4e14a
--- /dev/null
+++ b/dev/api/responses/users-update.json
@@ -0,0 +1,19 @@
+{
+  "id": 1,
+  "name": "Dan Spaggleforth",
+  "email": "dspaggles@example.com",
+  "created_at": "2022-02-03T16:27:55.000000Z",
+  "updated_at": "2022-02-03T16:27:55.000000Z",
+  "external_auth_id": "abc123456",
+  "slug": "dan-spaggleforth",
+  "last_activity_at": "2022-02-03T16:27:55.000000Z",
+  "profile_url": "https://docs.example.com/user/dan-spaggleforth",
+  "edit_url": "https://docs.example.com/settings/users/1",
+  "avatar_url": "https://docs.example.com/uploads/images/user/2021-10/thumbs-50-50/profile-2021.jpg",
+  "roles": [
+    {
+      "id": 2,
+      "display_name": "Editors"
+    }
+  ]
+}
\ No newline at end of file