diff --git a/app/Http/Controllers/Api/ImageGalleryApiController.php b/app/Http/Controllers/Api/ImageGalleryApiController.php index a9fb3b103..3dba3d464 100644 --- a/app/Http/Controllers/Api/ImageGalleryApiController.php +++ b/app/Http/Controllers/Api/ImageGalleryApiController.php @@ -34,8 +34,8 @@ class ImageGalleryApiController extends ApiController } /** - * Get a listing of gallery images and drawings in the system. - * Requires visibility of the content they're originally uploaded to. + * Get a listing of images in the system. Includes gallery (page content) images and drawings. + * Requires visibility of the page they're originally uploaded to. */ public function list() { @@ -50,6 +50,11 @@ class ImageGalleryApiController extends ApiController /** * Create a new image in the system. + * Since "image" is expected to be a file, this needs to be a 'multipart/form-data' type request. + * The provided "uploaded_to" should be an existing page ID in the system. + * If the "name" parameter is omitted, the filename of the provided image file will be used instead. + * The "type" parameter should be 'gallery' for page content images, and 'drawio' should only be used + * when the file is a PNG file with diagrams.net image data embedded within. */ public function create(Request $request) { @@ -69,6 +74,10 @@ class ImageGalleryApiController extends ApiController /** * View the details of a single image. + * The "thumbs" response property contains links to scaled variants that BookStack may use in its UI. + * The "content" response property provides HTML and Markdown content, in the format that BookStack + * would typically use by default to add the image in page content, as a convenience. + * Actual image file data is not provided but can be fetched via the "url" response property. */ public function read(string $id) { @@ -78,7 +87,8 @@ class ImageGalleryApiController extends ApiController } /** - * Update an existing image in the system. + * Update the details of an existing image in the system. + * Only allows updating of the image name at this time. */ public function update(Request $request, string $id) { @@ -94,6 +104,8 @@ class ImageGalleryApiController extends ApiController /** * Delete an image from the system. + * Will also delete thumbnails for the image. + * Does not check or handle image usage so this could leave pages with broken image references. */ public function delete(string $id) { diff --git a/dev/api/requests/image-gallery-update.json b/dev/api/requests/image-gallery-update.json new file mode 100644 index 000000000..e332e3a8f --- /dev/null +++ b/dev/api/requests/image-gallery-update.json @@ -0,0 +1,3 @@ +{ + "name": "My updated image name" +} \ No newline at end of file diff --git a/dev/api/responses/image-gallery-create.json b/dev/api/responses/image-gallery-create.json new file mode 100644 index 000000000..e27824491 --- /dev/null +++ b/dev/api/responses/image-gallery-create.json @@ -0,0 +1,28 @@ +{ + "name": "cute-cat-image.png", + "path": "\/uploads\/images\/gallery\/2023-03\/cute-cat-image.png", + "url": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/cute-cat-image.png", + "type": "gallery", + "uploaded_to": 1, + "created_by": { + "id": 1, + "name": "Admin", + "slug": "admin" + }, + "updated_by": { + "id": 1, + "name": "Admin", + "slug": "admin" + }, + "updated_at": "2023-03-15 08:17:37", + "created_at": "2023-03-15 08:17:37", + "id": 618, + "thumbs": { + "gallery": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/thumbs-150-150\/cute-cat-image.png", + "display": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/scaled-1680-\/cute-cat-image.png" + }, + "content": { + "html": "\"cute-cat-image.png\"<\/a>", + "markdown": "![cute-cat-image.png](https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/scaled-1680-\/cute-cat-image.png)" + } +} \ No newline at end of file diff --git a/dev/api/responses/image-gallery-list.json b/dev/api/responses/image-gallery-list.json new file mode 100644 index 000000000..054d68a15 --- /dev/null +++ b/dev/api/responses/image-gallery-list.json @@ -0,0 +1,41 @@ +{ + "data": [ + { + "id": 1, + "name": "My cat scribbles", + "url": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-02\/scribbles.jpg", + "path": "\/uploads\/images\/gallery\/2023-02\/scribbles.jpg", + "type": "gallery", + "uploaded_to": 1, + "created_by": 1, + "updated_by": 1, + "created_at": "2023-02-12T16:34:57.000000Z", + "updated_at": "2023-02-12T16:34:57.000000Z" + }, + { + "id": 2, + "name": "Drawing-1.png", + "url": "https:\/\/bookstack.example.com\/uploads\/images\/drawio\/2023-02\/drawing-1.png", + "path": "\/uploads\/images\/drawio\/2023-02\/drawing-1.png", + "type": "drawio", + "uploaded_to": 2, + "created_by": 2, + "updated_by": 2, + "created_at": "2023-02-12T16:39:19.000000Z", + "updated_at": "2023-02-12T16:39:19.000000Z" + }, + { + "id": 8, + "name": "beans.jpg", + "url": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-02\/beans.jpg", + "path": "\/uploads\/images\/gallery\/2023-02\/beans.jpg", + "type": "gallery", + "uploaded_to": 6, + "created_by": 1, + "updated_by": 1, + "created_at": "2023-02-15T19:37:44.000000Z", + "updated_at": "2023-02-15T19:37:44.000000Z" + } + ], + "total": 3 +} \ No newline at end of file diff --git a/dev/api/responses/image-gallery-read.json b/dev/api/responses/image-gallery-read.json new file mode 100644 index 000000000..c6c468daa --- /dev/null +++ b/dev/api/responses/image-gallery-read.json @@ -0,0 +1,28 @@ +{ + "id": 618, + "name": "cute-cat-image.png", + "url": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/cute-cat-image.png", + "created_at": "2023-03-15 08:17:37", + "updated_at": "2023-03-15 08:17:37", + "created_by": { + "id": 1, + "name": "Admin", + "slug": "admin" + }, + "updated_by": { + "id": 1, + "name": "Admin", + "slug": "admin" + }, + "path": "\/uploads\/images\/gallery\/2023-03\/cute-cat-image.png", + "type": "gallery", + "uploaded_to": 1, + "thumbs": { + "gallery": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/thumbs-150-150\/cute-cat-image.png", + "display": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/scaled-1680-\/cute-cat-image.png" + }, + "content": { + "html": "\"cute-cat-image.png\"<\/a>", + "markdown": "![cute-cat-image.png](https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/scaled-1680-\/cute-cat-image.png)" + } +} \ No newline at end of file diff --git a/dev/api/responses/image-gallery-update.json b/dev/api/responses/image-gallery-update.json new file mode 100644 index 000000000..6e6168a1b --- /dev/null +++ b/dev/api/responses/image-gallery-update.json @@ -0,0 +1,28 @@ +{ + "id": 618, + "name": "My updated image name", + "url": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/cute-cat-image.png", + "created_at": "2023-03-15 08:17:37", + "updated_at": "2023-03-15 08:24:50", + "created_by": { + "id": 1, + "name": "Admin", + "slug": "admin" + }, + "updated_by": { + "id": 1, + "name": "Admin", + "slug": "admin" + }, + "path": "\/uploads\/images\/gallery\/2023-03\/cute-cat-image.png", + "type": "gallery", + "uploaded_to": 1, + "thumbs": { + "gallery": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/thumbs-150-150\/cute-cat-image.png", + "display": "https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/scaled-1680-\/cute-cat-image.png" + }, + "content": { + "html": "\"My<\/a>", + "markdown": "![My updated image name](https:\/\/bookstack.example.com\/uploads\/images\/gallery\/2023-03\/scaled-1680-\/cute-cat-image.png)" + } +} \ No newline at end of file diff --git a/resources/views/api-docs/parts/getting-started.blade.php b/resources/views/api-docs/parts/getting-started.blade.php index 7358b5cd7..75b71c6be 100644 --- a/resources/views/api-docs/parts/getting-started.blade.php +++ b/resources/views/api-docs/parts/getting-started.blade.php @@ -14,11 +14,11 @@ HTTP POST calls upon events occurring in BookStack.
  • - Visual Theme System - + Visual Theme System - Methods to override views, translations and icons within BookStack.
  • - Logical Theme System - + Logical Theme System - Methods to extend back-end functionality within BookStack.