API: Added examples for comments

Tweaked comment repo to avoid returning a lot of extra data on API
update responses.

diff --git a/app/Activity/CommentRepo.php b/app/Activity/CommentRepo.php
index 13808903d9601bcbee893abe198791dbd80f1ca8..1802e39058574066151889fad48a0eda94b0c250 100644 (file)
--- a/app/Activity/CommentRepo.php
+++ b/app/Activity/CommentRepo.php
@@ -74,6 +74,7 @@ class CommentRepo
         ActivityService::add(ActivityType::COMMENT_CREATE, $comment);
         ActivityService::add(ActivityType::COMMENTED_ON, $entity);
 
+        $comment->refresh()->unsetRelations();
         return $comment;
     }
 

diff --git a/dev/api/requests/comments-create.json b/dev/api/requests/comments-create.json
new file mode 100644 (file)
index 0000000..abc6832
--- /dev/null
+++ b/dev/api/requests/comments-create.json
@@ -0,0 +1,5 @@
+{
+       "page_id": 2646,
+       "html": "<p>Can the title be updated?</p>",
+       "content_ref": "bkmrk-page-title:7341676876991010:3-14"
+}
\ No newline at end of file

diff --git a/dev/api/requests/comments-update.json b/dev/api/requests/comments-update.json
new file mode 100644 (file)
index 0000000..bbcf114
--- /dev/null
+++ b/dev/api/requests/comments-update.json
@@ -0,0 +1,4 @@
+{
+       "html": "<p>Can this comment be updated??????</p>",
+       "archived": true
+}
\ No newline at end of file

diff --git a/dev/api/responses/comments-create.json b/dev/api/responses/comments-create.json
new file mode 100644 (file)
index 0000000..6fec5c1
--- /dev/null
+++ b/dev/api/responses/comments-create.json
@@ -0,0 +1,13 @@
+{
+       "id": 167,
+       "commentable_id": 2646,
+       "commentable_type": "page",
+       "parent_id": null,
+       "local_id": 29,
+       "created_by": 1,
+       "updated_by": 1,
+       "created_at": "2025-10-24T14:05:41.000000Z",
+       "updated_at": "2025-10-24T14:05:41.000000Z",
+       "content_ref": "bkmrk-page-title:7341676876991010:3-14",
+       "archived": false
+}
\ No newline at end of file

diff --git a/dev/api/responses/comments-list.json b/dev/api/responses/comments-list.json
new file mode 100644 (file)
index 0000000..a0f6381
--- /dev/null
+++ b/dev/api/responses/comments-list.json
@@ -0,0 +1,29 @@
+{
+       "data": [
+               {
+                       "id": 1,
+                       "commentable_id": 2607,
+                       "commentable_type": "page",
+                       "parent_id": null,
+                       "local_id": 1,
+                       "content_ref": "",
+                       "created_by": 1,
+                       "updated_by": 1,
+                       "created_at": "2022-04-20T08:43:27.000000Z",
+                       "updated_at": "2022-04-20T08:43:27.000000Z"
+               },
+               {
+                       "id": 18,
+                       "commentable_id": 2607,
+                       "commentable_type": "page",
+                       "parent_id": 1,
+                       "local_id": 2,
+                       "content_ref": "",
+                       "created_by": 3,
+                       "updated_by": 3,
+                       "created_at": "2022-11-15T08:12:35.000000Z",
+                       "updated_at": "2022-11-15T08:12:35.000000Z"
+               }
+       ],
+       "total": 88
+}
\ No newline at end of file

diff --git a/dev/api/responses/comments-read.json b/dev/api/responses/comments-read.json
new file mode 100644 (file)
index 0000000..054b8ad
--- /dev/null
+++ b/dev/api/responses/comments-read.json
@@ -0,0 +1,38 @@
+{
+       "id": 22,
+       "commentable_id": 2646,
+       "commentable_type": "page",
+       "html": "<p>This page looks great!<\/p>\n",
+       "parent_id": null,
+       "local_id": 2,
+       "created_by": {
+               "id": 1,
+               "name": "Admin",
+               "slug": "admin"
+       },
+       "updated_by": {
+               "id": 1,
+               "name": "Admin",
+               "slug": "admin"
+       },
+       "created_at": "2023-06-07T07:50:56.000000Z",
+       "updated_at": "2023-06-07T07:50:56.000000Z",
+       "content_ref": "",
+       "archived": false,
+       "replies": [
+               {
+                       "id": 34,
+                       "commentable_id": 2646,
+                       "commentable_type": "page",
+                       "html": "<p>Thanks for the comment!<\/p>\n",
+                       "parent_id": 2,
+                       "local_id": 10,
+                       "created_by": 2,
+                       "updated_by": 2,
+                       "created_at": "2023-06-07T13:46:25.000000Z",
+                       "updated_at": "2023-06-07T13:46:25.000000Z",
+                       "content_ref": "",
+                       "archived": false
+               }
+       ]
+}
\ No newline at end of file

diff --git a/dev/api/responses/comments-update.json b/dev/api/responses/comments-update.json
new file mode 100644 (file)
index 0000000..ce5ed26
--- /dev/null
+++ b/dev/api/responses/comments-update.json
@@ -0,0 +1,13 @@
+{
+       "id": 167,
+       "commentable_id": 2646,
+       "commentable_type": "page",
+       "parent_id": null,
+       "local_id": 29,
+       "created_by": 1,
+       "updated_by": 1,
+       "created_at": "2025-10-24T14:05:41.000000Z",
+       "updated_at": "2025-10-24T14:09:56.000000Z",
+       "content_ref": "bkmrk-page-title:7341676876991010:3-14",
+       "archived": true
+}
\ No newline at end of file

diff --git a/dev/api/responses/pages-read.json b/dev/api/responses/pages-read.json
index 22ff2de84af5e7ab7b292c3759b685c2be69bc27..e38a9cf9242b4366a9a1b588a04fca8ce287eb5f 100644 (file)
--- a/dev/api/responses/pages-read.json
+++ b/dev/api/responses/pages-read.json
@@ -29,6 +29,79 @@
        "revision_count": 5,
        "template": false,
        "editor": "wysiwyg",
+       "comments": {
+               "active": [
+                       {
+                               "comment": {
+                                       "id": 22,
+                                       "commentable_id": 306,
+                                       "commentable_type": "page",
+                                       "html": "<p>Does this need revising?<\/p>\n",
+                                       "parent_id": null,
+                                       "local_id": 1,
+                                       "created_by": {
+                                               "id": 1,
+                                               "name": "Admin",
+                                               "slug": "admin"
+                                       },
+                                       "updated_by": 1,
+                                       "created_at": "2023-06-07T07:50:56.000000Z",
+                                       "updated_at": "2023-06-07T07:50:56.000000Z",
+                                       "content_ref": "",
+                                       "archived": false
+                               },
+                               "depth": 0,
+                               "children": [
+                                       {
+                                               "comment": {
+                                                       "id": 34,
+                                                       "commentable_id": 2646,
+                                                       "commentable_type": "page",
+                                                       "html": "<p>I think it's okay!<\/p>\n",
+                                                       "parent_id": 1,
+                                                       "local_id": 2,
+                                                       "created_by": {
+                                                               "id": 2,
+                                                               "name": "Editor",
+                                                               "slug": "editor"
+                                                       },
+                                                       "updated_by": 1,
+                                                       "created_at": "2023-06-07T13:46:25.000000Z",
+                                                       "updated_at": "2023-06-07T13:46:25.000000Z",
+                                                       "content_ref": "",
+                                                       "archived": false
+                                               },
+                                               "depth": 1,
+                                               "children": []
+                                       }
+                               ]
+                       }
+               ],
+               "archived": [
+                       {
+                               "comment": {
+                                       "id": 21,
+                                       "commentable_id": 2646,
+                                       "commentable_type": "page",
+                                       "html": "<p>The title needs to be fixed<\/p>\n",
+                                       "parent_id": null,
+                                       "local_id": 3,
+                                       "created_by": {
+                                               "id": 2,
+                                               "name": "Editor",
+                                               "slug": "editor"
+                                       },
+                                       "updated_by": 1,
+                                       "created_at": "2023-06-07T07:50:49.000000Z",
+                                       "updated_at": "2025-10-24T08:37:22.000000Z",
+                                       "content_ref": "",
+                                       "archived": true
+                               },
+                               "depth": 0,
+                               "children": []
+                       }
+               ]
+       },
        "tags": [
                {
                        "name": "Category",