1
0
mirror of https://github.com/BookStackApp/BookStack.git synced 2025-08-07 23:03:00 +03:00

API Docs: Allowed multi-paragraph descriptions

Added support for mulit-line endpoint descriptions via blank
intermediate lines in php controller method docblocks.

Also tweaks endpoint header design for better flexing and alignment.
This commit is contained in:
Dan Brown
2023-06-20 23:44:39 +01:00
parent 4bb2cf5c5f
commit 38883e8d46
6 changed files with 27 additions and 17 deletions

View File

@@ -16,8 +16,8 @@ use ReflectionMethod;
class ApiDocsGenerator
{
protected $reflectionClasses = [];
protected $controllerClasses = [];
protected array $reflectionClasses = [];
protected array $controllerClasses = [];
/**
* Load the docs form the cache if existing
@@ -139,9 +139,10 @@ class ApiDocsGenerator
protected function parseDescriptionFromMethodComment(string $comment): string
{
$matches = [];
preg_match_all('/^\s*?\*\s((?![@\s]).*?)$/m', $comment, $matches);
preg_match_all('/^\s*?\*\s?($|((?![\/@\s]).*?))$/m', $comment, $matches);
return implode(' ', $matches[1] ?? []);
$text = implode(' ', $matches[1] ?? []);
return str_replace(' ', "\n", $text);
}
/**

View File

@@ -82,7 +82,6 @@ class PageApiController extends ApiController
/**
* 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.
*

View File

@@ -38,8 +38,10 @@ class ContentPermissionApiController extends ApiController
/**
* Read the configured content-level permissions for the item of the given type and ID.
*
* 'contentType' should be one of: page, book, chapter, bookshelf.
* 'contentId' should be the relevant ID of that item type you'd like to handle permissions for.
*
* The permissions shown are those that override the default for just the specified item, they do not show the
* full evaluated permission for a role, nor do they reflect permissions inherited from other items in the hierarchy.
* Fallback permission values may be `null` when inheriting is active.
@@ -57,6 +59,7 @@ class ContentPermissionApiController extends ApiController
/**
* Update the configured content-level permission overrides for the item of the given type and ID.
* 'contentType' should be one of: page, book, chapter, bookshelf.
*
* 'contentId' should be the relevant ID of that item type you'd like to handle permissions for.
* Providing an empty `role_permissions` array will remove any existing configured role permissions,
* so you may want to fetch existing permissions beforehand if just adding/removing a single item.

View File

@@ -52,8 +52,10 @@ class ImageGalleryApiController extends ApiController
/**
* Create a new image in the system.
*
* Since "image" is expected to be a file, this needs to be a 'multipart/form-data' type request.
* The provided "uploaded_to" should be an existing page ID in the system.
*
* If the "name" parameter is omitted, the filename of the provided image file will be used instead.
* The "type" parameter should be 'gallery' for page content images, and 'drawio' should only be used
* when the file is a PNG file with diagrams.net image data embedded within.