Added attachment API examples during manual testing

ssddanbrown · ssddanbrown · commit 60d4c5902b1a · 2021-10-20T10:43:03.000+01:00
diff --git a/app/Http/Controllers/Api/AttachmentApiController.php b/app/Http/Controllers/Api/AttachmentApiController.php
@@ -52,6 +52,9 @@ public function list()
      * 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 @@ public function read(string $id)
 
     /**
      * 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
diff --git a/app/Uploads/Attachment.php b/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',
     ];
diff --git a/dev/api/requests/attachments-create.json b/dev/api/requests/attachments-create.json
@@ -0,0 +1,5 @@
+{
+  "name": "My uploaded attachment",
+  "uploaded_to": 8,
+  "link": "https://link.example.com"
+}
diff --git a/dev/api/requests/attachments-update.json b/dev/api/requests/attachments-update.json
@@ -0,0 +1,5 @@
+{
+  "name": "My updated attachment",
+  "uploaded_to": 4,
+  "link": "https://link.example.com/updated"
+}
diff --git a/dev/api/responses/attachments-create.json b/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"
+}
diff --git a/dev/api/responses/attachments-list.json b/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
+}
diff --git a/dev/api/responses/attachments-read.json b/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"
+}
diff --git a/dev/api/responses/attachments-update.json b/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"
+}
