Mirrors/BookStack
1
0
Fork 0
mirror of https://github.com/BookStackApp/BookStack.git synced 2025-02-01 12:41:37 +01:00
Code Issues Releases Wiki Activity

Added pages API doc examples

Browse Source 
Made some tweaks to related content and other examples while there.
This commit is contained in:
Dan Brown 2020-11-28 15:21:54 +00:00
parent 1c8102bb89
commit 53bcfe528d
No known key found for this signature in database
GPG Key ID: 46D9F943C24A2EF9
18 changed files with 221 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
app/Actions/Tag.php
View File

@ -5,7 +5,7 @@ use BookStack\Model;
class Tag extends Model
{
protected $fillable = ['name', 'value', 'order'];
protected $hidden = ['id', 'entity_id', 'entity_type'];
protected $hidden = ['id', 'entity_id', 'entity_type', 'created_at', 'updated_at'];
/**
* Get the entity that this tag belongs to

2
app/Entities/Models/Book.php
View File

@ -18,7 +18,7 @@ class Book extends Entity implements HasCoverImage
public $searchFactor = 2;
protected $fillable = ['name', 'description'];
protected $hidden = ['restricted', 'pivot', 'image_id'];
protected $hidden = ['restricted', 'pivot', 'image_id', 'deleted_at'];
/**
* Get the url for this book.

2
app/Entities/Models/Bookshelf.php
View File

@ -12,7 +12,7 @@ class Bookshelf extends Entity implements HasCoverImage
protected $fillable = ['name', 'description', 'image_id'];
protected $hidden = ['restricted', 'image_id'];
protected $hidden = ['restricted', 'image_id', 'deleted_at'];
/**
* Get the books in this shelf.

2
app/Entities/Models/Chapter.php
View File

@ -11,7 +11,7 @@ class Chapter extends BookChild
public $searchFactor = 1.3;
protected $fillable = ['name', 'description', 'priority', 'book_id'];
protected $hidden = ['restricted', 'pivot'];
protected $hidden = ['restricted', 'pivot', 'deleted_at'];
/**
* Get the pages that this chapter contains.

14
app/Entities/Models/Page.php
View File

@ -1,5 +1,6 @@
<?php namespace BookStack\Entities\Models;
use BookStack\Entities\Tools\PageContent;
use BookStack\Uploads\Attachment;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Collection;
@ -27,7 +28,7 @@ class Page extends BookChild
public $textField = 'text';
protected $hidden = ['html', 'markdown', 'text', 'restricted', 'pivot'];
protected $hidden = ['html', 'markdown', 'text', 'restricted', 'pivot', 'deleted_at'];
protected $casts = [
'draft' => 'boolean',
@ -114,4 +115,15 @@ class Page extends BookChild
{
return $this->revisions()->first();
}
/**
* Get this page for JSON display.
*/
public function forJsonDisplay(): Page
{
$refreshed = $this->refresh()->unsetRelations()->load(['tags', 'createdBy', 'updatedBy']);
$refreshed->setHidden(array_diff($refreshed->getHidden(), ['html', 'markdown']));
$refreshed->html = (new PageContent($refreshed))->render();
return $refreshed;
}
}

3
app/Http/Controllers/Api/BookApiController.php
View File

@ -79,7 +79,8 @@ class BookApiController extends ApiController
}
/**
* Delete a single book from the system.
* Delete a single book.
* This will typically send the book to the recycle bin.
* @throws \Exception
*/
public function delete(string $id)

3
app/Http/Controllers/Api/BookshelfApiController.php
View File

@ -100,7 +100,8 @@ class BookshelfApiController extends ApiController
/**
* Delete a single shelf from the system.
* Delete a single shelf.
* This will typically send the shelf to the recycle bin.
* @throws Exception
*/
public function delete(string $id)

3
app/Http/Controllers/Api/ChapterApiController.php
View File

@ -86,7 +86,8 @@ class ChapterApiController extends ApiController
}
/**
* Delete a chapter from the system.
* Delete a chapter.
* This will typically send the chapter to the recycle bin.
*/
public function delete(string $id)
{

28
app/Http/Controllers/Api/PageApiController.php
View File

@ -16,8 +16,8 @@ class PageApiController extends ApiController
protected $rules = [
'create' => [
'book_id' => 'required_unless:chapter_id|integer',
'chapter_id' => 'required_unless:book_id|integer',
'book_id' => 'required_without:chapter_id|integer',
'chapter_id' => 'required_without:book_id|integer',
'name' => 'required|string|max:255',
'html' => 'required_without:markdown|string',
'markdown' => 'required_without:html|string',
@ -53,6 +53,12 @@ class PageApiController extends ApiController
/**
* Create a new page in the system.
*
* The ID of a parent book or chapter is required to indicate
* where this page should be located.
*
* Any HTML content provided should be kept to a single-block depth of plain HTML
* elements to remain compatible with the BookStack front-end and editors.
*/
public function create(Request $request)
{
@ -68,20 +74,27 @@ class PageApiController extends ApiController
$draft = $this->pageRepo->getNewDraftPage($parent);
$this->pageRepo->publishDraft($draft, $request->only(array_keys($this->rules['create'])));
return response()->json($draft->load(['tags']));
return response()->json($draft->forJsonDisplay());
}
/**
* View the details of a single page.
*
* Pages will always have HTML content. They may have markdown content
* if the markdown editor was used to last update the page.
*/
public function read(string $id)
{
$page = $this->pageRepo->getById($id, ['tags', 'createdBy', 'updatedBy']);
return response()->json($page);
$page = $this->pageRepo->getById($id, []);
return response()->json($page->forJsonDisplay());
}
/**
* Update the details of a single page.
*
* See the 'create' action for details on the provided HTML/Markdown.
* Providing a 'book_id' or 'chapter_id' property will essentially move
* the page into that parent element if you have permissions to do so.
*/
public function update(Request $request, string $id)
{
@ -109,11 +122,12 @@ class PageApiController extends ApiController
}
$updatedPage = $this->pageRepo->update($page, $request->all());
return response()->json($updatedPage->load(['tags']));
return response()->json($updatedPage->forJsonDisplay());
}
/**
* Delete a page from the system.
* Delete a page.
* This will typically send the page to the recycle bin.
*/
public function delete(string $id)
{

9
dev/api/requests/pages-create.json Normal file
View File

@ -0,0 +1,9 @@
{
"book_id": 1,
"name": "My API Page",
"html": "<p>my new API page</p>",
"tags": [
{"name": "Category", "value": "Not Bad Content"},
{"name": "Rating", "value": "Average"}
]
}

9
dev/api/requests/pages-update.json Normal file
View File

@ -0,0 +1,9 @@
{
"chapter_id": 1,
"name": "My updated API Page",
"html": "<p>my new API page - Updated</p>",
"tags": [
{"name": "Category", "value": "API Examples"},
{"name": "Rating", "value": "Alright"}
]
}

6
dev/api/responses/books-read.json
View File

@ -16,13 +16,9 @@
"tags": [
{
"id": 13,
"entity_id": 16,
"entity_type": "BookStack\\Book",
"name": "Category",
"value": "Guide",
"order": 0,
"created_at": "2020-01-12 14:11:51",
"updated_at": "2020-01-12 14:11:51"
"order": 0
}
],
"cover": {

12
dev/api/responses/chapters-read.json
View File

@ -19,9 +19,7 @@
{
"name": "Category",
"value": "Guide",
"order": 0,
"created_at": "2020-05-22 22:51:51",
"updated_at": "2020-05-22 22:51:51"
"order": 0
}
],
"pages": [
@ -36,9 +34,9 @@
"updated_at": "2019-08-26 14:32:59",
"created_by": 1,
"updated_by": 1,
"draft": 0,
"draft": false,
"revision_count": 2,
"template": 0
"template": false
},
{
"id": 7,
@ -51,9 +49,9 @@
"updated_at": "2019-06-06 12:03:04",
"created_by": 3,
"updated_by": 3,
"draft": 0,
"draft": false,
"revision_count": 1,
"template": 0
"template": false
}
]
}

35
dev/api/responses/pages-create.json Normal file
View File

@ -0,0 +1,35 @@
{
"id": 358,
"book_id": 1,
"chapter_id": 0,
"name": "My API Page",
"slug": "my-api-page",
"html": "<p id=\"bkmrk-my-new-api-page\">my new API page</p>",
"priority": 14,
"created_at": "2020-11-28 15:01:39",
"updated_at": "2020-11-28 15:01:39",
"created_by": {
"id": 1,
"name": "Admin"
},
"updated_by": {
"id": 1,
"name": "Admin"
},
"draft": false,
"markdown": "",
"revision_count": 1,
"template": false,
"tags": [
{
"name": "Category",
"value": "Not Bad Content",
"order": 0
},
{
"name": "Rating",
"value": "Average",
"order": 1
}
]
}

47
dev/api/responses/pages-list.json Normal file
View File

@ -0,0 +1,47 @@
{
"data": [
{
"id": 1,
"book_id": 1,
"chapter_id": 1,
"name": "How to create page content",
"slug": "how-to-create-page-content",
"priority": 0,
"draft": false,
"template": false,
"created_at": "2019-05-05 21:49:58",
"updated_at": "2020-07-04 15:50:58",
"created_by": 1,
"updated_by": 1
},
{
"id": 2,
"book_id": 1,
"chapter_id": 1,
"name": "How to use images",
"slug": "how-to-use-images",
"priority": 2,
"draft": false,
"template": false,
"created_at": "2019-05-05 21:53:30",
"updated_at": "2019-06-06 12:03:04",
"created_by": 1,
"updated_by": 1
},
{
"id": 3,
"book_id": 1,
"chapter_id": 1,
"name": "Drawings via draw.io",
"slug": "drawings-via-drawio",
"priority": 3,
"draft": false,
"template": false,
"created_at": "2019-05-05 21:53:49",
"updated_at": "2019-12-18 21:56:52",
"created_by": 1,
"updated_by": 1
}
],
"total": 322
}

35
dev/api/responses/pages-read.json Normal file
View File

@ -0,0 +1,35 @@
{
"id": 306,
"book_id": 1,
"chapter_id": 0,
"name": "A page written in markdown",
"slug": "a-page-written-in-markdown",
"html": "<h1 id=\"bkmrk-how-this-is-built\">How this is built</h1>\r\n<p id=\"bkmrk-this-page-is-written\">This page is written in markdown. BookStack stores the page data in HTML.</p>\r\n<p id=\"bkmrk-here%27s-a-cute-pictur\">Here's a cute picture of my cat:</p>\r\n<p id=\"bkmrk-\"><a href=\"http://example.com/uploads/images/gallery/2020-04/yXSrubes.jpg\"><img src=\"http://example.com/uploads/images/gallery/2020-04/scaled-1680-/yXSrubes.jpg\" alt=\"yXSrubes.jpg\"></a></p>",
"priority": 13,
"created_at": "2020-02-02 21:40:38",
"updated_at": "2020-11-28 14:43:20",
"created_by": {
"id": 1,
"name": "Admin"
},
"updated_by": {
"id": 1,
"name": "Admin"
},
"draft": false,
"markdown": "# How this is built\r\n\r\nThis page is written in markdown. BookStack stores the page data in HTML.\r\n\r\nHere's a cute picture of my cat:\r\n\r\n[![yXSrubes.jpg](http://example.com/uploads/images/gallery/2020-04/scaled-1680-/yXSrubes.jpg)](http://example.com/uploads/images/gallery/2020-04/yXSrubes.jpg)",
"revision_count": 5,
"template": false,
"tags": [
{
"name": "Category",
"value": "Top Content",
"order": 0
},
{
"name": "Animal",
"value": "Cat",
"order": 1
}
]
}

35
dev/api/responses/pages-update.json Normal file
View File

@ -0,0 +1,35 @@
{
"id": 361,
"book_id": 1,
"chapter_id": 1,
"name": "My updated API Page",
"slug": "my-updated-api-page",
"html": "<p id=\"bkmrk-my-new-api-page---up\">my new API page - Updated</p>",
"priority": 16,
"created_at": "2020-11-28 15:10:54",
"updated_at": "2020-11-28 15:13:03",
"created_by": {
"id": 1,
"name": "Admin"
},
"updated_by": {
"id": 1,
"name": "Admin"
},
"draft": false,
"markdown": "",
"revision_count": 5,
"template": false,
"tags": [
{
"name": "Category",
"value": "API Examples",
"order": 0
},
{
"name": "Rating",
"value": "Alright",
"order": 0
}
]
}

6
dev/api/responses/shelves-read.json
View File

@ -16,13 +16,9 @@
"tags": [
{
"id": 16,
"entity_id": 14,
"entity_type": "BookStack\\Bookshelf",
"name": "Category",
"value": "Guide",
"order": 0,
"created_at": "2020-04-10 13:31:04",
"updated_at": "2020-04-10 13:31:04"
"order": 0
}
],
"cover": {