Added attachment API examples during manual testing

diff --git a/app/Http/Controllers/Api/AttachmentApiController.php b/app/Http/Controllers/Api/AttachmentApiController.php
index 7aa4ee4934b89cd7b8aec08aeff335a6fd6f2319..353cb058d82c9ccfc6a1c52f8a196d1b91ed57af 100644 (file)
--- a/app/Http/Controllers/Api/AttachmentApiController.php
+++ b/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.
      *
      * 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
      */
      * @throws ValidationException
      * @throws FileUploadException
      */


@@ -108,6 +111,8 @@ class AttachmentApiController extends ApiController
 
     /**
      * Update the details of a single attachment.
 
     /**
      * 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
      *
      * @throws ValidationException
      * @throws FileUploadException

diff --git a/app/Uploads/Attachment.php b/app/Uploads/Attachment.php
index 8ae53199e1d54edf4233d6455a2ce6dd2780930e..410a7d4ddd1cb2b14cd202a7ab41a7fe1ac3dec2 100644 (file)
--- a/app/Uploads/Attachment.php
+++ b/app/Uploads/Attachment.php
@@ -29,7 +29,7 @@ class Attachment extends Model
     use HasCreatorAndUpdater;
 
     protected $fillable = ['name', 'order'];
     use HasCreatorAndUpdater;
 
     protected $fillable = ['name', 'order'];

-    protected $hidden = ['path'];
+    protected $hidden = ['path', 'page'];

     protected $casts = [
         'external' => 'bool',
     ];
     protected $casts = [
         'external' => 'bool',
     ];

diff --git a/dev/api/requests/attachments-create.json b/dev/api/requests/attachments-create.json
new file mode 100644 (file)
index 0000000..8ed34b2
--- /dev/null
+++ b/dev/api/requests/attachments-create.json
@@ -0,0 +1,5 @@
+{
+  "name": "My uploaded attachment",
+  "uploaded_to": 8,
+  "link": "https://link.example.com"
+}
\ No newline at end of file

diff --git a/dev/api/requests/attachments-update.json b/dev/api/requests/attachments-update.json
new file mode 100644 (file)
index 0000000..062050b
--- /dev/null
+++ b/dev/api/requests/attachments-update.json
@@ -0,0 +1,5 @@
+{
+  "name": "My updated attachment",
+  "uploaded_to": 4,
+  "link": "https://link.example.com/updated"
+}
\ No newline at end of file

diff --git a/dev/api/responses/attachments-create.json b/dev/api/responses/attachments-create.json
new file mode 100644 (file)
index 0000000..5af524e
--- /dev/null
+++ 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"
+}
\ No newline at end of file

diff --git a/dev/api/responses/attachments-list.json b/dev/api/responses/attachments-list.json
new file mode 100644 (file)
index 0000000..946dd54
--- /dev/null
+++ 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
+}
\ No newline at end of file

diff --git a/dev/api/responses/attachments-read.json b/dev/api/responses/attachments-read.json
new file mode 100644 (file)
index 0000000..e22f4e5
--- /dev/null
+++ 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"
+}
\ No newline at end of file

diff --git a/dev/api/responses/attachments-update.json b/dev/api/responses/attachments-update.json
new file mode 100644 (file)
index 0000000..8054b0e
--- /dev/null
+++ 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"
+}
\ No newline at end of file