NOW MANAGED ON CODEBERG
API: Re-ordered routes, Improved navigation
Dan Brownd40a68b41142
diff --git a/resources/js/components/api-nav.ts b/resources/js/components/api-nav.tsnew file mode 100644index 000000000..a84c1cb33--- /dev/null+++ b/resources/js/components/api-nav.ts@@ -0,0 +1,32 @@+import {Component} from "./component";++export class ApiNav extends Component {+ private select!: HTMLSelectElement;+ private sidebar!: HTMLElement;+ private body!: HTMLElement;++ setup() {+ this.select = this.$refs.select as HTMLSelectElement;+ this.sidebar = this.$refs.sidebar;+ this.body = this.$el.ownerDocument.documentElement;+ this.select.addEventListener('change', () => {+ const section = this.select.value;+ const sidebarTarget = document.getElementById(`sidebar-header-${section}`);+ const contentTarget = document.getElementById(`section-${section}`);+ if (sidebarTarget && contentTarget) {++ const sidebarPos = sidebarTarget.getBoundingClientRect().top - this.sidebar.getBoundingClientRect().top + this.sidebar.scrollTop;+ this.sidebar.scrollTo({+ top: sidebarPos - 120,+ behavior: 'smooth',+ });++ const bodyPos = contentTarget.getBoundingClientRect().top + this.body.scrollTop;+ this.body.scrollTo({+ top: bodyPos - 20,+ behavior: 'smooth',+ });+ }+ });+ }+}\ No newline at end of filediff --git a/resources/js/components/index.ts b/resources/js/components/index.tsindex 63e1ad0db..736d93f05 100644--- a/resources/js/components/index.ts+++ b/resources/js/components/index.ts@@ -1,6 +1,7 @@export {AddRemoveRows} from './add-remove-rows';export {AjaxDeleteRow} from './ajax-delete-row';export {AjaxForm} from './ajax-form';+export {ApiNav} from './api-nav';export {Attachments} from './attachments';export {AttachmentsList} from './attachments-list';export {AutoSuggest} from './auto-suggest';diff --git a/resources/sass/_blocks.scss b/resources/sass/_blocks.scssindex 8c248caee..4857c2cee 100644--- a/resources/sass/_blocks.scss+++ b/resources/sass/_blocks.scss@@ -274,7 +274,19 @@.sticky-sidebar {position: sticky;- top: vars.$m;- max-height: calc(100vh - #{vars.$m});+ top: 0;+ padding-left: 2px;+ max-height: calc(100vh);overflow-y: auto;+ .sticky-sidebar-header {+ position: sticky;+ top: 0;+ background: #F2F2F2;+ background: linear-gradient(180deg,rgba(242, 242, 242, 1) 66%, rgba(242, 242, 242, 0) 100%);+ z-index: 4;+ }+}+.dark-mode .sticky-sidebar-header {+ background: #111;+ background: linear-gradient(180deg,rgba(17, 17, 17, 1) 66%, rgba(17, 17, 17, 0) 100%);}diff --git a/resources/views/api-docs/index.blade.php b/resources/views/api-docs/index.blade.phpindex 84c6d21ac..c331f0707 100644--- a/resources/views/api-docs/index.blade.php+++ b/resources/views/api-docs/index.blade.php@@ -2,48 +2,65 @@@section('body')- <div class="container pt-xl">+ <div component="api-nav" class="container"><div class="grid right-focus reverse-collapse"><div>- <div class="sticky-sidebar">- <p class="text-uppercase text-muted mb-xm mt-l"><strong>Getting Started</strong></p>+ <div refs="api-nav@sidebar" class="sticky-sidebar">- <div class="text-mono">- <div class="mb-xs"><a href="#authentication">Authentication</a></div>- <div class="mb-xs"><a href="#request-format">Request Format</a></div>- <div class="mb-xs"><a href="#listing-endpoints">Listing Endpoints</a></div>- <div class="mb-xs"><a href="#error-handling">Error Handling</a></div>- <div class="mb-xs"><a href="#rate-limits">Rate Limits</a></div>- <div class="mb-xs"><a href="#content-security">Content Security</a></div>+ <div class="sticky-sidebar-header py-xl">+ <select refs="api-nav@select" name="navigation" id="navigation">+ <option value="getting-started" selected>Jump To Section</option>+ <option value="getting-started">Getting Started</option>+ @foreach($docs as $model => $endpoints)+ <option value="{{ str_replace(' ', '-', $model) }}">{{ ucfirst($model) }}</option>+ @if($model === 'docs' || $model === 'shelves')+ <hr>+ @endif+ @endforeach+ </select>+ </div>++ <div class="mb-xl">+ <p id="sidebar-header-getting-started" class="text-uppercase text-muted mb-xm"><strong>Getting Started</strong></p>+ <div class="text-mono">+ <div class="mb-xs"><a href="#authentication">Authentication</a></div>+ <div class="mb-xs"><a href="#request-format">Request Format</a></div>+ <div class="mb-xs"><a href="#listing-endpoints">Listing Endpoints</a></div>+ <div class="mb-xs"><a href="#error-handling">Error Handling</a></div>+ <div class="mb-xs"><a href="#rate-limits">Rate Limits</a></div>+ <div class="mb-xs"><a href="#content-security">Content Security</a></div>+ </div></div>@foreach($docs as $model => $endpoints)- <p class="text-uppercase text-muted mb-xm mt-l"><strong>{{ $model }}</strong></p>+ <div class="mb-xl">+ <p id="sidebar-header-{{ str_replace(' ', '-', $model) }}" class="text-uppercase text-muted mb-xm"><strong>{{ $model }}</strong></p>- @foreach($endpoints as $endpoint)- <div class="mb-xs">- <a href="#{{ $endpoint['name'] }}" class="text-mono inline block mr-s">- <span class="api-method" data-method="{{ $endpoint['method'] }}">{{ $endpoint['method'] }}</span>- </a>- <a href="#{{ $endpoint['name'] }}" class="text-mono">- {{ $endpoint['controller_method_kebab'] }}- </a>- </div>- @endforeach+ @foreach($endpoints as $endpoint)+ <div class="mb-xs">+ <a href="#{{ $endpoint['name'] }}" class="text-mono inline block mr-s">+ <span class="api-method" data-method="{{ $endpoint['method'] }}">{{ $endpoint['method'] }}</span>+ </a>+ <a href="#{{ $endpoint['name'] }}" class="text-mono">+ {{ $endpoint['controller_method_kebab'] }}+ </a>+ </div>+ @endforeach+ </div>@endforeach</div></div>- <div style="overflow: auto;">+ <div class="pt-xl" style="overflow: auto;">- <section component="code-highlighter" class="card content-wrap auto-height">+ <section id="section-getting-started" component="code-highlighter" class="card content-wrap auto-height">@include('api-docs.parts.getting-started')</section>@foreach($docs as $model => $endpoints)- <section class="card content-wrap auto-height">+ <section id="section-{{ str_replace(' ', '-', $model) }}" class="card content-wrap auto-height"><h1 class="list-heading text-capitals">{{ $model }}</h1>@if($endpoints[0]['model_description'])<p>{{ $endpoints[0]['model_description'] }}</p>diff --git a/routes/api.php b/routes/api.phpindex 1466e638c..308a95d8c 100644--- a/routes/api.php+++ b/routes/api.php@@ -2,7 +2,7 @@/*** Routes for the BookStack API.- * Routes have a uri prefix of /api/.+ * Routes have a URI prefix of /api/.* Controllers all end with "ApiController"*/@@ -19,25 +19,18 @@ use BookStack\Users\Controllers\RoleApiController;use BookStack\Users\Controllers\UserApiController;use Illuminate\Support\Facades\Route;-Route::get('docs.json', [ApiDocsController::class, 'json']);--Route::get('attachments', [AttachmentApiController::class, 'list']);-Route::post('attachments', [AttachmentApiController::class, 'create']);-Route::get('attachments/{id}', [AttachmentApiController::class, 'read']);-Route::put('attachments/{id}', [AttachmentApiController::class, 'update']);-Route::delete('attachments/{id}', [AttachmentApiController::class, 'delete']);+// Main Entity Routes-Route::get('books', [EntityControllers\BookApiController::class, 'list']);-Route::post('books', [EntityControllers\BookApiController::class, 'create']);-Route::get('books/{id}', [EntityControllers\BookApiController::class, 'read']);-Route::put('books/{id}', [EntityControllers\BookApiController::class, 'update']);-Route::delete('books/{id}', [EntityControllers\BookApiController::class, 'delete']);--Route::get('books/{id}/export/html', [ExportControllers\BookExportApiController::class, 'exportHtml']);-Route::get('books/{id}/export/pdf', [ExportControllers\BookExportApiController::class, 'exportPdf']);-Route::get('books/{id}/export/plaintext', [ExportControllers\BookExportApiController::class, 'exportPlainText']);-Route::get('books/{id}/export/markdown', [ExportControllers\BookExportApiController::class, 'exportMarkdown']);-Route::get('books/{id}/export/zip', [ExportControllers\BookExportApiController::class, 'exportZip']);+Route::get('pages', [EntityControllers\PageApiController::class, 'list']);+Route::post('pages', [EntityControllers\PageApiController::class, 'create']);+Route::get('pages/{id}', [EntityControllers\PageApiController::class, 'read']);+Route::put('pages/{id}', [EntityControllers\PageApiController::class, 'update']);+Route::delete('pages/{id}', [EntityControllers\PageApiController::class, 'delete']);+Route::get('pages/{id}/export/html', [ExportControllers\PageExportApiController::class, 'exportHtml']);+Route::get('pages/{id}/export/pdf', [ExportControllers\PageExportApiController::class, 'exportPdf']);+Route::get('pages/{id}/export/plaintext', [ExportControllers\PageExportApiController::class, 'exportPlainText']);+Route::get('pages/{id}/export/markdown', [ExportControllers\PageExportApiController::class, 'exportMarkdown']);+Route::get('pages/{id}/export/zip', [ExportControllers\PageExportApiController::class, 'exportZip']);Route::get('chapters', [EntityControllers\ChapterApiController::class, 'list']);Route::post('chapters', [EntityControllers\ChapterApiController::class, 'create']);@@ -50,27 +43,32 @@ Route::get('chapters/{id}/export/plaintext', [ExportControllers\ChapterExportApiRoute::get('chapters/{id}/export/markdown', [ExportControllers\ChapterExportApiController::class, 'exportMarkdown']);Route::get('chapters/{id}/export/zip', [ExportControllers\ChapterExportApiController::class, 'exportZip']);-Route::get('pages', [EntityControllers\PageApiController::class, 'list']);-Route::post('pages', [EntityControllers\PageApiController::class, 'create']);-Route::get('pages/{id}', [EntityControllers\PageApiController::class, 'read']);-Route::put('pages/{id}', [EntityControllers\PageApiController::class, 'update']);-Route::delete('pages/{id}', [EntityControllers\PageApiController::class, 'delete']);+Route::get('books', [EntityControllers\BookApiController::class, 'list']);+Route::post('books', [EntityControllers\BookApiController::class, 'create']);+Route::get('books/{id}', [EntityControllers\BookApiController::class, 'read']);+Route::put('books/{id}', [EntityControllers\BookApiController::class, 'update']);+Route::delete('books/{id}', [EntityControllers\BookApiController::class, 'delete']);+Route::get('books/{id}/export/html', [ExportControllers\BookExportApiController::class, 'exportHtml']);+Route::get('books/{id}/export/pdf', [ExportControllers\BookExportApiController::class, 'exportPdf']);+Route::get('books/{id}/export/plaintext', [ExportControllers\BookExportApiController::class, 'exportPlainText']);+Route::get('books/{id}/export/markdown', [ExportControllers\BookExportApiController::class, 'exportMarkdown']);+Route::get('books/{id}/export/zip', [ExportControllers\BookExportApiController::class, 'exportZip']);-Route::get('pages/{id}/export/html', [ExportControllers\PageExportApiController::class, 'exportHtml']);-Route::get('pages/{id}/export/pdf', [ExportControllers\PageExportApiController::class, 'exportPdf']);-Route::get('pages/{id}/export/plaintext', [ExportControllers\PageExportApiController::class, 'exportPlainText']);-Route::get('pages/{id}/export/markdown', [ExportControllers\PageExportApiController::class, 'exportMarkdown']);-Route::get('pages/{id}/export/zip', [ExportControllers\PageExportApiController::class, 'exportZip']);+Route::get('shelves', [EntityControllers\BookshelfApiController::class, 'list']);+Route::post('shelves', [EntityControllers\BookshelfApiController::class, 'create']);+Route::get('shelves/{id}', [EntityControllers\BookshelfApiController::class, 'read']);+Route::put('shelves/{id}', [EntityControllers\BookshelfApiController::class, 'update']);+Route::delete('shelves/{id}', [EntityControllers\BookshelfApiController::class, 'delete']);-Route::get('image-gallery', [ImageGalleryApiController::class, 'list']);-Route::post('image-gallery', [ImageGalleryApiController::class, 'create']);-Route::get('image-gallery/url/data', [ImageGalleryApiController::class, 'readDataForUrl']);-Route::get('image-gallery/{id}', [ImageGalleryApiController::class, 'read']);-Route::get('image-gallery/{id}/data', [ImageGalleryApiController::class, 'readData']);-Route::put('image-gallery/{id}', [ImageGalleryApiController::class, 'update']);-Route::delete('image-gallery/{id}', [ImageGalleryApiController::class, 'delete']);+// Additional Model Routes, in alphabetical order-Route::get('search', [SearchApiController::class, 'all']);+Route::get('attachments', [AttachmentApiController::class, 'list']);+Route::post('attachments', [AttachmentApiController::class, 'create']);+Route::get('attachments/{id}', [AttachmentApiController::class, 'read']);+Route::put('attachments/{id}', [AttachmentApiController::class, 'update']);+Route::delete('attachments/{id}', [AttachmentApiController::class, 'delete']);++Route::get('audit-log', [ActivityControllers\AuditLogApiController::class, 'list']);Route::get('comments', [ActivityControllers\CommentApiController::class, 'list']);Route::post('comments', [ActivityControllers\CommentApiController::class, 'create']);@@ -78,23 +76,18 @@ Route::get('comments/{id}', [ActivityControllers\CommentApiController::class, 'rRoute::put('comments/{id}', [ActivityControllers\CommentApiController::class, 'update']);Route::delete('comments/{id}', [ActivityControllers\CommentApiController::class, 'delete']);-Route::get('shelves', [EntityControllers\BookshelfApiController::class, 'list']);-Route::post('shelves', [EntityControllers\BookshelfApiController::class, 'create']);-Route::get('shelves/{id}', [EntityControllers\BookshelfApiController::class, 'read']);-Route::put('shelves/{id}', [EntityControllers\BookshelfApiController::class, 'update']);-Route::delete('shelves/{id}', [EntityControllers\BookshelfApiController::class, 'delete']);+Route::get('content-permissions/{contentType}/{contentId}', [ContentPermissionApiController::class, 'read']);+Route::put('content-permissions/{contentType}/{contentId}', [ContentPermissionApiController::class, 'update']);-Route::get('users', [UserApiController::class, 'list']);-Route::post('users', [UserApiController::class, 'create']);-Route::get('users/{id}', [UserApiController::class, 'read']);-Route::put('users/{id}', [UserApiController::class, 'update']);-Route::delete('users/{id}', [UserApiController::class, 'delete']);+Route::get('docs.json', [ApiDocsController::class, 'json']);-Route::get('roles', [RoleApiController::class, 'list']);-Route::post('roles', [RoleApiController::class, 'create']);-Route::get('roles/{id}', [RoleApiController::class, 'read']);-Route::put('roles/{id}', [RoleApiController::class, 'update']);-Route::delete('roles/{id}', [RoleApiController::class, 'delete']);+Route::get('image-gallery', [ImageGalleryApiController::class, 'list']);+Route::post('image-gallery', [ImageGalleryApiController::class, 'create']);+Route::get('image-gallery/url/data', [ImageGalleryApiController::class, 'readDataForUrl']);+Route::get('image-gallery/{id}', [ImageGalleryApiController::class, 'read']);+Route::get('image-gallery/{id}/data', [ImageGalleryApiController::class, 'readData']);+Route::put('image-gallery/{id}', [ImageGalleryApiController::class, 'update']);+Route::delete('image-gallery/{id}', [ImageGalleryApiController::class, 'delete']);Route::get('imports', [ExportControllers\ImportApiController::class, 'list']);Route::post('imports', [ExportControllers\ImportApiController::class, 'create']);@@ -106,9 +99,18 @@ Route::get('recycle-bin', [EntityControllers\RecycleBinApiController::class, 'liRoute::put('recycle-bin/{deletionId}', [EntityControllers\RecycleBinApiController::class, 'restore']);Route::delete('recycle-bin/{deletionId}', [EntityControllers\RecycleBinApiController::class, 'destroy']);-Route::get('content-permissions/{contentType}/{contentId}', [ContentPermissionApiController::class, 'read']);-Route::put('content-permissions/{contentType}/{contentId}', [ContentPermissionApiController::class, 'update']);+Route::get('roles', [RoleApiController::class, 'list']);+Route::post('roles', [RoleApiController::class, 'create']);+Route::get('roles/{id}', [RoleApiController::class, 'read']);+Route::put('roles/{id}', [RoleApiController::class, 'update']);+Route::delete('roles/{id}', [RoleApiController::class, 'delete']);-Route::get('audit-log', [ActivityControllers\AuditLogApiController::class, 'list']);+Route::get('search', [SearchApiController::class, 'all']);Route::get('system', [SystemApiController::class, 'read']);++Route::get('users', [UserApiController::class, 'list']);+Route::post('users', [UserApiController::class, 'create']);+Route::get('users/{id}', [UserApiController::class, 'read']);+Route::put('users/{id}', [UserApiController::class, 'update']);+Route::delete('users/{id}', [UserApiController::class, 'delete']);