Changelog: Tweaked spacing, count and element referencing

[bookstack] / app / Exports / Controllers / ImportApiController.php

diff --git a/app/Exports/Controllers/ImportApiController.php b/app/Exports/Controllers/ImportApiController.php
index 13bc9d83ea5e027ab03260103ef502006cac2695..cac155c7c1b13576e90be3769ec2a8465b5cead6 100644 (file)
--- a/app/Exports/Controllers/ImportApiController.php
+++ b/app/Exports/Controllers/ImportApiController.php
@@ -23,28 +23,37 @@ class ImportApiController extends ApiController
 
     /**
      * List existing ZIP imports visible to the user.
+     * Requires permission to import content.
      */
     public function list(): JsonResponse
     {
-        $imports = $this->imports->getVisibleImports()->all();
+        $query = $this->imports->queryVisible();
 
-        return response()->json($imports);
+        return $this->apiListingResponse($query, [
+            'id', 'name', 'size', 'type', 'created_by', 'created_at', 'updated_at'
+        ]);
     }
 
     /**
-     * Upload, validate and store a ZIP import file.
-     * This does not run the import. That is performed via a separate endpoint.
+     * Start a new import from a ZIP file.
+     * This does not actually run the import since that is performed via the "run" endpoint.
+     * This uploads, validates and stores the ZIP file so it's ready to be imported.
+     *
+     * This "file" parameter must be a BookStack-compatible ZIP file, and this must be
+     * sent via a 'multipart/form-data' type request.
+     *
+     * Requires permission to import content.
      */
-    public function upload(Request $request): JsonResponse
+    public function create(Request $request): JsonResponse
     {
-        $this->validate($request, $this->rules()['upload']);
+        $this->validate($request, $this->rules()['create']);
 
         $file = $request->file('file');
 
         try {
             $import = $this->imports->storeFromUpload($file);
         } catch (ZipValidationException $exception) {
-            $message = "ZIP upload failed with the following validation errors: \n" . implode("\n", $exception->errors);
+            $message = "ZIP upload failed with the following validation errors: \n" . $this->formatErrors($exception->errors);
             return $this->jsonError($message, 422);
         }
 
@@ -53,18 +62,24 @@ class ImportApiController extends ApiController
 
     /**
      * Read details of a pending ZIP import.
+     * The "details" property contains high-level metadata regarding the ZIP import content,
+     * and the structure of this will change depending on import "type".
+     * Requires permission to import content.
      */
     public function read(int $id): JsonResponse
     {
         $import = $this->imports->findVisible($id);
 
+        $import->setAttribute('details', $import->decodeMetadata());
+
         return response()->json($import);
     }
 
     /**
      * Run the import process for an uploaded ZIP import.
-     * The parent_id and parent_type parameters are required when the import type is 'chapter' or 'page'.
-     * On success, returns the imported item.
+     * The "parent_id" and "parent_type" parameters are required when the import type is "chapter" or "page".
+     * On success, this endpoint returns the imported item.
+     * Requires permission to import content.
      */
     public function run(int $id, Request $request): JsonResponse
     {
@@ -82,15 +97,16 @@ class ImportApiController extends ApiController
         try {
             $entity = $this->imports->runImport($import, $parent);
         } catch (ZipImportException $exception) {
-            $message = "ZIP import failed with the following errors: \n" . implode("\n", $exception->errors);
+            $message = "ZIP import failed with the following errors: \n" . $this->formatErrors($exception->errors);
             return $this->jsonError($message);
         }
 
-        return response()->json($entity);
+        return response()->json($entity->withoutRelations());
     }
 
     /**
-     * Delete a pending ZIP import.
+     * Delete a pending ZIP import from the system.
+     * Requires permission to import content.
      */
     public function delete(int $id): Response
     {
@@ -103,7 +119,7 @@ class ImportApiController extends ApiController
     protected function rules(): array
     {
         return [
-            'upload' => [
+            'create' => [
                 'file' => ['required', ...AttachmentService::getFileValidationRules()],
             ],
             'run' => [
@@ -112,4 +128,17 @@ class ImportApiController extends ApiController
             ],
         ];
     }
+
+    protected function formatErrors(array $errors): string
+    {
+        $parts = [];
+        foreach ($errors as $key => $error) {
+            if (is_string($key)) {
+                $parts[] = "[{$key}] {$error}";
+            } else {
+                $parts[] = $error;
+            }
+        }
+        return implode("\n", $parts);
+    }
 }