Added attachment API examples during manual testing

app/Http/Controllers/Api/AttachmentApiController.php

@@ -52,6 +52,9 @@ class AttachmentApiController extends ApiController
      * An uploaded_to value must be provided containing an ID of the page
      * that this upload will be related to.
      *
+     * If you're uploading a file the POST data should be provided via
+     * a multipart/form-data type request instead of JSON.
+     *
      * @throws ValidationException
      * @throws FileUploadException
      */
@@ -108,6 +111,8 @@ class AttachmentApiController extends ApiController
 
     /**
      * Update the details of a single attachment.
+     * As per the create endpoint, if a file is being provided as the attachment content
+     * the request should be formatted as a multipart/form-data request instead of JSON.
      *
      * @throws ValidationException
      * @throws FileUploadException

app/Uploads/Attachment.php

@@ -29,7 +29,7 @@ class Attachment extends Model
     use HasCreatorAndUpdater;
 
     protected $fillable = ['name', 'order'];
-    protected $hidden = ['path'];
+    protected $hidden = ['path', 'page'];
     protected $casts = [
         'external' => 'bool',
     ];

dev/api/requests/attachments-create.json

@@ -0,0 +1,5 @@
+{
+  "name": "My uploaded attachment",
+  "uploaded_to": 8,
+  "link": "https://link.example.com"
+}

dev/api/requests/attachments-update.json

@@ -0,0 +1,5 @@
+{
+  "name": "My updated attachment",
+  "uploaded_to": 4,
+  "link": "https://link.example.com/updated"
+}

dev/api/responses/attachments-create.json

@@ -0,0 +1,12 @@
+{
+  "id": 5,
+  "name": "My uploaded attachment",
+  "extension": "",
+  "uploaded_to": 8,
+  "external": true,
+  "order": 2,
+  "created_by": 1,
+  "updated_by": 1,
+  "created_at": "2021-10-20 06:35:46",
+  "updated_at": "2021-10-20 06:35:46"
+}

dev/api/responses/attachments-list.json

@@ -0,0 +1,29 @@
+{
+  "data": [
+    {
+      "id": 3,
+      "name": "datasheet.pdf",
+      "extension": "pdf",
+      "uploaded_to": 8,
+      "external": false,
+      "order": 1,
+      "created_at": "2021-10-11 06:18:49",
+      "updated_at": "2021-10-20 06:31:10",
+      "created_by": 1,
+      "updated_by": 1
+    },
+    {
+      "id": 4,
+      "name": "Cat reference",
+      "extension": "",
+      "uploaded_to": 9,
+      "external": true,
+      "order": 1,
+      "created_at": "2021-10-20 06:30:11",
+      "updated_at": "2021-10-20 06:30:11",
+      "created_by": 1,
+      "updated_by": 1
+    }
+  ],
+  "total": 2
+}

dev/api/responses/attachments-read.json

@@ -0,0 +1,25 @@
+{
+  "id": 5,
+  "name": "My link attachment",
+  "extension": "",
+  "uploaded_to": 4,
+  "external": true,
+  "order": 2,
+  "created_by": {
+    "id": 1,
+    "name": "Admin",
+    "slug": "admin"
+  },
+  "updated_by": {
+    "id": 1,
+    "name": "Admin",
+    "slug": "admin"
+  },
+  "created_at": "2021-10-20 06:35:46",
+  "updated_at": "2021-10-20 06:37:11",
+  "links": {
+    "html": "<a target=\"_blank\" href=\"https://bookstack.local/attachments/5\">My updated attachment</a>",
+    "markdown": "[My updated attachment](https://bookstack.local/attachments/5)"
+  },
+  "content": "https://link.example.com/updated"
+}

dev/api/responses/attachments-update.json

@@ -0,0 +1,12 @@
+{
+  "id": 5,
+  "name": "My updated attachment",
+  "extension": "",
+  "uploaded_to": 4,
+  "external": true,
+  "order": 2,
+  "created_by": 1,
+  "updated_by": 1,
+  "created_at": "2021-10-20 06:35:46",
+  "updated_at": "2021-10-20 06:37:11"
+}