Added pages API doc examples

Made some tweaks to related content and other examples while there.

diff --git a/app/Actions/Tag.php b/app/Actions/Tag.php
index 709b1ddebc04fd88d853371b07fe8de577908880..5968ffe6d5ea9d875cf4fa574ac63d3d4c8d62a1 100644 (file)
--- 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'];
 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
 
     /**
      * Get the entity that this tag belongs to

diff --git a/app/Entities/Models/Book.php b/app/Entities/Models/Book.php
index afa2cde497578b3316f067006b5d1a6bb4048aa5..6c56767655c894b22c548e7ff552a07f36940ea6 100644 (file)
--- 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'];
     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.
 
     /**
      * Get the url for this book.

diff --git a/app/Entities/Models/Bookshelf.php b/app/Entities/Models/Bookshelf.php
index edba8f61f05d5f7b3c94d1d8c7ad7e1790ceca75..8ffd06d2e2f1b9d22dee6cabb23318976c85ddac 100644 (file)
--- 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 $fillable = ['name', 'description', 'image_id'];
 

-    protected $hidden = ['restricted', 'image_id'];
+    protected $hidden = ['restricted', 'image_id', 'deleted_at'];

 
     /**
      * Get the books in this shelf.
 
     /**
      * Get the books in this shelf.

diff --git a/app/Entities/Models/Chapter.php b/app/Entities/Models/Chapter.php
index fc1d2c9d56be18913983340f32bc97e4684207bc..d736e2108d405194d7f0c93f92056a0a2abf2172 100644 (file)
--- 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'];
     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.
 
     /**
      * Get the pages that this chapter contains.

diff --git a/app/Entities/Models/Page.php b/app/Entities/Models/Page.php
index b0a3e2d3185143a9265e6079c3b615e88e5579a6..52c64f0480af78fc64a30bae48c8f05b1d108407 100644 (file)
--- a/app/Entities/Models/Page.php
+++ b/app/Entities/Models/Page.php
@@ -1,5 +1,6 @@
 <?php namespace BookStack\Entities\Models;
 
 <?php namespace BookStack\Entities\Models;
 

+use BookStack\Entities\Tools\PageContent;

 use BookStack\Uploads\Attachment;
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Collection;
 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';
 
 
     public $textField = 'text';
 

-    protected $hidden = ['html', 'markdown', 'text', 'restricted', 'pivot'];
+    protected $hidden = ['html', 'markdown', 'text', 'restricted', 'pivot', 'deleted_at'];

 
     protected $casts = [
         'draft' => 'boolean',
 
     protected $casts = [
         'draft' => 'boolean',


@@ -114,4 +115,15 @@ class Page extends BookChild
     {
         return $this->revisions()->first();
     }
     {
         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 b7a5796c6d940f70fc3a329c38b524d0bf9f2bcf..1b25b9645288e9ccc3afc80b2a631423d509c98a 100644 (file)
--- 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)
      * @throws \Exception
      */
     public function delete(string $id)

diff --git a/app/Http/Controllers/Api/BookshelfApiController.php b/app/Http/Controllers/Api/BookshelfApiController.php
index 7f6aaa69f572225a26a8f302a67b313eceb75e13..c4851b003f6cc012d12658362e40f3d1608336f4 100644 (file)
--- 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)
      * @throws Exception
      */
     public function delete(string $id)

diff --git a/app/Http/Controllers/Api/ChapterApiController.php b/app/Http/Controllers/Api/ChapterApiController.php
index c7dd38c1b63b4f4e7d3f48ac50198955d5c44513..e69aecc2ddcd9df9141e30f30edd2bcd821bd590 100644 (file)
--- 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)
     {
      */
     public function delete(string $id)
     {

diff --git a/app/Http/Controllers/Api/PageApiController.php b/app/Http/Controllers/Api/PageApiController.php
index 2fc4e3b36d3f246b4364b04a409c95626680ae44..0b3323ccd61bffaabcd1e3df45fcf31acaedb6ea 100644 (file)
--- 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' => [
 
     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',
             '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.
 
     /**
      * 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)
     {
      */
     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'])));
 
         $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.
     }
 
     /**
      * 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)
     {
      */
     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.
     }
 
     /**
      * 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)
     {
      */
     public function update(Request $request, string $id)
     {


@@ -109,11 +122,12 @@ class PageApiController extends ApiController
         }
 
         $updatedPage = $this->pageRepo->update($page, $request->all());
         }
 
         $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)
     {
      */
     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 (file)
index 0000000..1f53b42
--- /dev/null
+++ b/dev/api/requests/pages-create.json
@@ -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"}
+       ]
+}
\ 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 (file)
index 0000000..b9bfeb6
--- /dev/null
+++ b/dev/api/requests/pages-update.json
@@ -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"}
+       ]
+}
\ No newline at end of file

diff --git a/dev/api/responses/books-read.json b/dev/api/responses/books-read.json
index 2e43f5f87fc810163bc8323f53e304c6cbb070db..815a71c3573d139806145654a5547ef21dccd410 100644 (file)
--- a/dev/api/responses/books-read.json
+++ b/dev/api/responses/books-read.json
@@ -16,13 +16,9 @@
   "tags": [
     {
       "id": 13,
   "tags": [
     {
       "id": 13,

-      "entity_id": 16,
-      "entity_type": "BookStack\\Book",

       "name": "Category",
       "value": "Guide",
       "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": {
     }
   ],
   "cover": {

diff --git a/dev/api/responses/chapters-read.json b/dev/api/responses/chapters-read.json
index 2eddad8955070a36b15df967df96a3b7e7aa7dd7..0d16f4b6a30ffadc438e0c3dc9e7d0eafc6b5c98 100644 (file)
--- a/dev/api/responses/chapters-read.json
+++ b/dev/api/responses/chapters-read.json
@@ -19,9 +19,7 @@
     {
       "name": "Category",
       "value": "Guide",
     {
       "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": [
     }
   ],
   "pages": [


@@ -36,9 +34,9 @@
       "updated_at": "2019-08-26 14:32:59",
       "created_by": 1,
       "updated_by": 1,
       "updated_at": "2019-08-26 14:32:59",
       "created_by": 1,
       "updated_by": 1,

-      "draft": 0,
+      "draft": false,

       "revision_count": 2,
       "revision_count": 2,

-      "template": 0
+      "template": false

     },
     {
       "id": 7,
     },
     {
       "id": 7,


@@ -51,9 +49,9 @@
       "updated_at": "2019-06-06 12:03:04",
       "created_by": 3,
       "updated_by": 3,
       "updated_at": "2019-06-06 12:03:04",
       "created_by": 3,
       "updated_by": 3,

-      "draft": 0,
+      "draft": false,

       "revision_count": 1,
       "revision_count": 1,

-      "template": 0
+      "template": false

     }
   ]
 }
\ No newline at end of file
     }
   ]
 }
\ 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 (file)
index 0000000..1f6c970
--- /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": "<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
+               }
+       ]
+}
\ 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 (file)
index 0000000..9739345
--- /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 (file)
index 0000000..c8acb52
--- /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": "<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
+               }
+       ]
+}
\ 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 (file)
index 0000000..23f8d22
--- /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": "<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
+               }
+       ]
+}
\ No newline at end of file

diff --git a/dev/api/responses/shelves-read.json b/dev/api/responses/shelves-read.json
index 634fbb5a53c6fde235e72c2516b111a73f645451..b0487debe7f0a98796beab3b9b5892c4d1f0aab8 100644 (file)
--- a/dev/api/responses/shelves-read.json
+++ b/dev/api/responses/shelves-read.json
@@ -16,13 +16,9 @@
   "tags": [
     {
       "id": 16,
   "tags": [
     {
       "id": 16,

-      "entity_id": 14,
-      "entity_type": "BookStack\\Bookshelf",

       "name": "Category",
       "value": "Guide",
       "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": {
     }
   ],
   "cover": {