Skip to content

Commit 32ba3a5

Browse files
ssddanbrownssddanbrown
committed
ZIP Imports: Added API examples, finished testing
Also updated some types on a couple of controllers.
1 parent 7302571 commit 32ba3a5

File tree

13 files changed

+130
-18
lines changed

13 files changed

+130
-18
lines changed

‎app/Entities/Controllers/ChapterApiController.php

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,12 +9,11 @@
99
use BookStack\Exceptions\PermissionsException;
1010
use BookStack\Http\ApiController;
1111
use Exception;
12-
use Illuminate\Database\Eloquent\Relations\HasMany;
1312
use Illuminate\Http\Request;
1413

1514
class ChapterApiController extends ApiController
1615
{
17-
protected $rules = [
16+
protected array $rules = [
1817
'create' => [
1918
'book_id' => ['required', 'integer'],
2019
'name' => ['required', 'string', 'max:255'],

‎app/Entities/Controllers/PageApiController.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212

1313
class PageApiController extends ApiController
1414
{
15-
protected $rules = [
15+
protected array $rules = [
1616
'create' => [
1717
'book_id' => ['required_without:chapter_id', 'integer'],
1818
'chapter_id' => ['required_without:book_id', 'integer'],

‎app/Exports/Controllers/ImportApiController.php

Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ public function __construct(
2323

2424
/**
2525
* List existing ZIP imports visible to the user.
26+
* Requires permission to import content.
2627
*/
2728
public function list(): JsonResponse
2829
{
@@ -34,12 +35,18 @@ public function list(): JsonResponse
3435
}
3536

3637
/**
37-
* Upload, validate and store a ZIP import file.
38-
* This does not run the import. That is performed via a separate endpoint.
38+
* Start a new import from a ZIP file.
39+
* This does not actually run the import since that is performed via the "run" endpoint.
40+
* This uploads, validates and stores the ZIP file so it's ready to be imported.
41+
*
42+
* This "file" parameter must be a BookStack-compatible ZIP file, and this must be
43+
* sent via a 'multipart/form-data' type request.
44+
*
45+
* Requires permission to import content.
3946
*/
40-
public function upload(Request $request): JsonResponse
47+
public function create(Request $request): JsonResponse
4148
{
42-
$this->validate($request, $this->rules()['upload']);
49+
$this->validate($request, $this->rules()['create']);
4350

4451
$file = $request->file('file');
4552

@@ -57,6 +64,7 @@ public function upload(Request $request): JsonResponse
5764
* Read details of a pending ZIP import.
5865
* The "details" property contains high-level metadata regarding the ZIP import content,
5966
* and the structure of this will change depending on import "type".
67+
* Requires permission to import content.
6068
*/
6169
public function read(int $id): JsonResponse
6270
{
@@ -69,8 +77,9 @@ public function read(int $id): JsonResponse
6977

7078
/**
7179
* Run the import process for an uploaded ZIP import.
72-
* The parent_id and parent_type parameters are required when the import type is 'chapter' or 'page'.
73-
* On success, returns the imported item.
80+
* The "parent_id" and "parent_type" parameters are required when the import type is "chapter" or "page".
81+
* On success, this endpoint returns the imported item.
82+
* Requires permission to import content.
7483
*/
7584
public function run(int $id, Request $request): JsonResponse
7685
{
@@ -92,11 +101,12 @@ public function run(int $id, Request $request): JsonResponse
92101
return $this->jsonError($message);
93102
}
94103

95-
return response()->json($entity);
104+
return response()->json($entity->withoutRelations());
96105
}
97106

98107
/**
99-
* Delete a pending ZIP import.
108+
* Delete a pending ZIP import from the system.
109+
* Requires permission to import content.
100110
*/
101111
public function delete(int $id): Response
102112
{
@@ -109,7 +119,7 @@ public function delete(int $id): Response
109119
protected function rules(): array
110120
{
111121
return [
112-
'upload' => [
122+
'create' => [
113123
'file' => ['required', ...AttachmentService::getFileValidationRules()],
114124
],
115125
'run' => [

‎app/Permissions/ContentPermissionApiController.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ public function __construct(
1616
) {
1717
}
1818

19-
protected $rules = [
19+
protected array $rules = [
2020
'update' => [
2121
'owner_id' => ['int'],
2222

‎app/Search/SearchApiController.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99

1010
class SearchApiController extends ApiController
1111
{
12-
protected $rules = [
12+
protected array $rules = [
1313
'all' => [
1414
'query' => ['required'],
1515
'page' => ['integer', 'min:1'],

‎app/Users/Controllers/RoleApiController.php

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ class RoleApiController extends ApiController
1616
'display_name', 'description', 'mfa_enforced', 'external_auth_id', 'created_at', 'updated_at',
1717
];
1818

19-
protected $rules = [
19+
protected array $rules = [
2020
'create' => [
2121
'display_name' => ['required', 'string', 'min:3', 'max:180'],
2222
'description' => ['string', 'max:180'],

‎dev/api/requests/imports-run.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"parent_type": "book",
3+
"parent_id": 28
4+
}

‎dev/api/responses/imports-create.json

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"type": "chapter",
3+
"name": "Pension Providers",
4+
"created_by": 1,
5+
"size": 2757,
6+
"path": "uploads\/files\/imports\/ghnxmS3u9QxLWu82.zip",
7+
"updated_at": "2025-07-18T14:50:27.000000Z",
8+
"created_at": "2025-07-18T14:50:27.000000Z",
9+
"id": 31
10+
}

‎dev/api/responses/imports-list.json

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{
2+
"data": [
3+
{
4+
"id": 25,
5+
"name": "IT Department",
6+
"size": 618462,
7+
"type": "book",
8+
"created_by": 1,
9+
"created_at": "2024-12-20T18:40:38.000000Z",
10+
"updated_at": "2024-12-20T18:40:38.000000Z"
11+
},
12+
{
13+
"id": 27,
14+
"name": "Clients",
15+
"size": 15364,
16+
"type": "chapter",
17+
"created_by": 1,
18+
"created_at": "2025-03-20T12:41:44.000000Z",
19+
"updated_at": "2025-03-20T12:41:44.000000Z"
20+
}
21+
],
22+
"total": 2
23+
}

‎dev/api/responses/imports-read.json

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
{
2+
"id": 25,
3+
"name": "IT Department",
4+
"path": "uploads\/files\/imports\/7YOpZ6sGIEbYdRFL.zip",
5+
"size": 618462,
6+
"type": "book",
7+
"created_by": 1,
8+
"created_at": "2024-12-20T18:40:38.000000Z",
9+
"updated_at": "2024-12-20T18:40:38.000000Z",
10+
"details": {
11+
"id": 4,
12+
"name": "IT Department",
13+
"chapters": [
14+
{
15+
"id": 3,
16+
"name": "Server Systems",
17+
"priority": 1,
18+
"pages": [
19+
{
20+
"id": 22,
21+
"name": "prod-aws-stonehawk",
22+
"priority": 0,
23+
"attachments": [],
24+
"images": [],
25+
"tags": []
26+
}
27+
],
28+
"tags": []
29+
}
30+
],
31+
"pages": [
32+
{
33+
"id": 23,
34+
"name": "Member Onboarding Guide",
35+
"priority": 0,
36+
"attachments": [],
37+
"images": [],
38+
"tags": []
39+
},
40+
{
41+
"id": 25,
42+
"name": "IT Holiday Party Event",
43+
"priority": 2,
44+
"attachments": [],
45+
"images": [],
46+
"tags": []
47+
}
48+
],
49+
"tags": []
50+
}
51+
}

0 commit comments

Comments
 (0)