docs(preview): Improve API parameter descriptions

Signed-off-by: provokateurin <[email protected]>
nextcloud · May 13, 2024 · dd997b6 · dd997b6
1 parent c31d6b1
commit dd997b6
Show file tree

Hide file tree

Showing 2 changed files with 24 additions and 16 deletions.
diff --git a/core/Controller/PreviewController.php b/core/Controller/PreviewController.php
@@ -61,11 +61,11 @@ public function __construct(
 	 * Get a preview by file path
 	 *
 	 * @param string $file Path of the file
-	 * @param int $x Width of the preview
-	 * @param int $y Height of the preview
-	 * @param bool $a Whether to not crop the preview
+	 * @param int $x Width of the preview. A width of -1 will use the original image width.
+	 * @param int $y Height of the preview. A height of -1 will use the original image height.
+	 * @param bool $a Preserve the aspect ratio
 	 * @param bool $forceIcon Force returning an icon
-	 * @param string $mode How to crop the image
+	 * @param 'fill'|'cover' $mode How to crop the image
 	 * @param bool $mimeFallback Whether to fallback to the mime icon if no preview is available
 	 * @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: string}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, array{}>|RedirectResponse<Http::STATUS_SEE_OTHER, array{}>
 	 *
@@ -105,11 +105,11 @@ public function getPreview(
 	 * Get a preview by file ID
 	 *
 	 * @param int $fileId ID of the file
-	 * @param int $x Width of the preview
-	 * @param int $y Height of the preview
-	 * @param bool $a Whether to not crop the preview
+	 * @param int $x Width of the preview. A width of -1 will use the original image width.
+	 * @param int $y Height of the preview. A height of -1 will use the original image height.
+	 * @param bool $a Preserve the aspect ratio
 	 * @param bool $forceIcon Force returning an icon
-	 * @param string $mode How to crop the image
+	 * @param 'fill'|'cover' $mode How to crop the image
 	 * @param bool $mimeFallback Whether to fallback to the mime icon if no preview is available
 	 * @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: string}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, array{}>|RedirectResponse<Http::STATUS_SEE_OTHER, array{}>
 	 *

diff --git a/core/openapi.json b/core/openapi.json
@@ -6212,7 +6212,7 @@
                     {
                         "name": "x",
                         "in": "query",
-                        "description": "Width of the preview",
+                        "description": "Width of the preview. A width of -1 will use the original image width.",
                         "schema": {
                             "type": "integer",
                             "format": "int64",
@@ -6222,7 +6222,7 @@
                     {
                         "name": "y",
                         "in": "query",
-                        "description": "Height of the preview",
+                        "description": "Height of the preview. A height of -1 will use the original image height.",
                         "schema": {
                             "type": "integer",
                             "format": "int64",
@@ -6232,7 +6232,7 @@
                     {
                         "name": "a",
                         "in": "query",
-                        "description": "Whether to not crop the preview",
+                        "description": "Preserve the aspect ratio",
                         "schema": {
                             "type": "integer",
                             "default": 0,
@@ -6261,7 +6261,11 @@
                         "description": "How to crop the image",
                         "schema": {
                             "type": "string",
-                            "default": "fill"
+                            "default": "fill",
+                            "enum": [
+                                "fill",
+                                "cover"
+                            ]
                         }
                     },
                     {
@@ -6356,7 +6360,7 @@
                     {
                         "name": "x",
                         "in": "query",
-                        "description": "Width of the preview",
+                        "description": "Width of the preview. A width of -1 will use the original image width.",
                         "schema": {
                             "type": "integer",
                             "format": "int64",
@@ -6366,7 +6370,7 @@
                     {
                         "name": "y",
                         "in": "query",
-                        "description": "Height of the preview",
+                        "description": "Height of the preview. A height of -1 will use the original image height.",
                         "schema": {
                             "type": "integer",
                             "format": "int64",
@@ -6376,7 +6380,7 @@
                     {
                         "name": "a",
                         "in": "query",
-                        "description": "Whether to not crop the preview",
+                        "description": "Preserve the aspect ratio",
                         "schema": {
                             "type": "integer",
                             "default": 0,
@@ -6405,7 +6409,11 @@
                         "description": "How to crop the image",
                         "schema": {
                             "type": "string",
-                            "default": "fill"
+                            "default": "fill",
+                            "enum": [
+                                "fill",
+                                "cover"
+                            ]
                         }
                     },
                     {