From 53bcfe528d96938132eb168433ea1fee9b9fd935 Mon Sep 17 00:00:00 2001 From: Dan Brown Date: Sat, 28 Nov 2020 15:21:54 +0000 Subject: [PATCH] Added pages API doc examples Made some tweaks to related content and other examples while there. --- app/Actions/Tag.php | 2 +- app/Entities/Models/Book.php | 2 +- app/Entities/Models/Bookshelf.php | 2 +- app/Entities/Models/Chapter.php | 2 +- app/Entities/Models/Page.php | 14 +++++- .../Controllers/Api/BookApiController.php | 3 +- .../Api/BookshelfApiController.php | 3 +- .../Controllers/Api/ChapterApiController.php | 3 +- .../Controllers/Api/PageApiController.php | 28 ++++++++--- dev/api/requests/pages-create.json | 9 ++++ dev/api/requests/pages-update.json | 9 ++++ dev/api/responses/books-read.json | 6 +-- dev/api/responses/chapters-read.json | 12 ++--- dev/api/responses/pages-create.json | 35 ++++++++++++++ dev/api/responses/pages-list.json | 47 +++++++++++++++++++ dev/api/responses/pages-read.json | 35 ++++++++++++++ dev/api/responses/pages-update.json | 35 ++++++++++++++ dev/api/responses/shelves-read.json | 6 +-- 18 files changed, 221 insertions(+), 32 deletions(-) create mode 100644 dev/api/requests/pages-create.json create mode 100644 dev/api/requests/pages-update.json create mode 100644 dev/api/responses/pages-create.json create mode 100644 dev/api/responses/pages-list.json create mode 100644 dev/api/responses/pages-read.json create mode 100644 dev/api/responses/pages-update.json diff --git a/app/Actions/Tag.php b/app/Actions/Tag.php index 709b1ddeb..5968ffe6d 100644 --- a/app/Actions/Tag.php +++ b/app/Actions/Tag.php @@ -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 diff --git a/app/Entities/Models/Book.php b/app/Entities/Models/Book.php index afa2cde49..6c5676765 100644 --- a/app/Entities/Models/Book.php +++ b/app/Entities/Models/Book.php @@ -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. diff --git a/app/Entities/Models/Bookshelf.php b/app/Entities/Models/Bookshelf.php index edba8f61f..8ffd06d2e 100644 --- a/app/Entities/Models/Bookshelf.php +++ b/app/Entities/Models/Bookshelf.php @@ -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. diff --git a/app/Entities/Models/Chapter.php b/app/Entities/Models/Chapter.php index fc1d2c9d5..d736e2108 100644 --- a/app/Entities/Models/Chapter.php +++ b/app/Entities/Models/Chapter.php @@ -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. diff --git a/app/Entities/Models/Page.php b/app/Entities/Models/Page.php index b0a3e2d31..52c64f048 100644 --- a/app/Entities/Models/Page.php +++ b/app/Entities/Models/Page.php @@ -1,5 +1,6 @@ '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; + } } diff --git a/app/Http/Controllers/Api/BookApiController.php b/app/Http/Controllers/Api/BookApiController.php index b7a5796c6..1b25b9645 100644 --- a/app/Http/Controllers/Api/BookApiController.php +++ b/app/Http/Controllers/Api/BookApiController.php @@ -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) diff --git a/app/Http/Controllers/Api/BookshelfApiController.php b/app/Http/Controllers/Api/BookshelfApiController.php index 7f6aaa69f..c4851b003 100644 --- a/app/Http/Controllers/Api/BookshelfApiController.php +++ b/app/Http/Controllers/Api/BookshelfApiController.php @@ -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) diff --git a/app/Http/Controllers/Api/ChapterApiController.php b/app/Http/Controllers/Api/ChapterApiController.php index c7dd38c1b..e69aecc2d 100644 --- a/app/Http/Controllers/Api/ChapterApiController.php +++ b/app/Http/Controllers/Api/ChapterApiController.php @@ -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) { diff --git a/app/Http/Controllers/Api/PageApiController.php b/app/Http/Controllers/Api/PageApiController.php index 2fc4e3b36..0b3323ccd 100644 --- a/app/Http/Controllers/Api/PageApiController.php +++ b/app/Http/Controllers/Api/PageApiController.php @@ -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) { diff --git a/dev/api/requests/pages-create.json b/dev/api/requests/pages-create.json new file mode 100644 index 000000000..1f53b42d4 --- /dev/null +++ b/dev/api/requests/pages-create.json @@ -0,0 +1,9 @@ +{ + "book_id": 1, + "name": "My API Page", + "html": "

my new API page

", + "tags": [ + {"name": "Category", "value": "Not Bad Content"}, + {"name": "Rating", "value": "Average"} + ] +} \ No newline at end of file diff --git a/dev/api/requests/pages-update.json b/dev/api/requests/pages-update.json new file mode 100644 index 000000000..b9bfeb630 --- /dev/null +++ b/dev/api/requests/pages-update.json @@ -0,0 +1,9 @@ +{ + "chapter_id": 1, + "name": "My updated API Page", + "html": "

my new API page - Updated

", + "tags": [ + {"name": "Category", "value": "API Examples"}, + {"name": "Rating", "value": "Alright"} + ] +} \ No newline at end of file diff --git a/dev/api/responses/books-read.json b/dev/api/responses/books-read.json index 2e43f5f87..815a71c35 100644 --- a/dev/api/responses/books-read.json +++ b/dev/api/responses/books-read.json @@ -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": { diff --git a/dev/api/responses/chapters-read.json b/dev/api/responses/chapters-read.json index 2eddad895..0d16f4b6a 100644 --- a/dev/api/responses/chapters-read.json +++ b/dev/api/responses/chapters-read.json @@ -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 } ] } \ No newline at end of file diff --git a/dev/api/responses/pages-create.json b/dev/api/responses/pages-create.json new file mode 100644 index 000000000..1f6c970fb --- /dev/null +++ b/dev/api/responses/pages-create.json @@ -0,0 +1,35 @@ +{ + "id": 358, + "book_id": 1, + "chapter_id": 0, + "name": "My API Page", + "slug": "my-api-page", + "html": "

my new API page

", + "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 + } + ] +} \ No newline at end of file diff --git a/dev/api/responses/pages-list.json b/dev/api/responses/pages-list.json new file mode 100644 index 000000000..973934516 --- /dev/null +++ b/dev/api/responses/pages-list.json @@ -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 +} \ No newline at end of file diff --git a/dev/api/responses/pages-read.json b/dev/api/responses/pages-read.json new file mode 100644 index 000000000..c8acb520a --- /dev/null +++ b/dev/api/responses/pages-read.json @@ -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": "

How this is built

\r\n

This page is written in markdown. BookStack stores the page data in HTML.

\r\n

Here's a cute picture of my cat:

\r\n

\"yXSrubes.jpg\"

", + "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 + } + ] +} \ No newline at end of file diff --git a/dev/api/responses/pages-update.json b/dev/api/responses/pages-update.json new file mode 100644 index 000000000..23f8d221c --- /dev/null +++ b/dev/api/responses/pages-update.json @@ -0,0 +1,35 @@ +{ + "id": 361, + "book_id": 1, + "chapter_id": 1, + "name": "My updated API Page", + "slug": "my-updated-api-page", + "html": "

my new API page - Updated

", + "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 + } + ] +} \ No newline at end of file diff --git a/dev/api/responses/shelves-read.json b/dev/api/responses/shelves-read.json index 634fbb5a5..b0487debe 100644 --- a/dev/api/responses/shelves-read.json +++ b/dev/api/responses/shelves-read.json @@ -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": {