fix(OpenAPI): Adjust array syntax to avoid ambiguitiesfix/openapi/array-syntax

Signed-off-by: provokateurin <kate@provokateurin.de>

9 files changed, 185 insertions, 44 deletions

diff --git a/apps/files/lib/Capabilities.php b/apps/files/lib/Capabilities.php
index d20d348a9f5..16ea42eae22 100644
--- a/apps/files/lib/Capabilities.php
+++ b/apps/files/lib/Capabilities.php
@@ -21,7 +21,7 @@ class Capabilities implements ICapability {
 	/**
 	 * Return this classes capabilities
 	 *
-	 * @return array{files: array{'$comment': ?string, bigfilechunking: bool, blacklisted_files: array<mixed>, forbidden_filenames: list<string>, forbidden_filename_basenames: list<string>, forbidden_filename_characters: list<string>, forbidden_filename_extensions: list<string>, chunked_upload: array{max_size: int, max_parallel_count: int}}}
+	 * @return array{files: array{'$comment': ?string, bigfilechunking: bool, blacklisted_files: list<mixed>, forbidden_filenames: list<string>, forbidden_filename_basenames: list<string>, forbidden_filename_characters: list<string>, forbidden_filename_extensions: list<string>, chunked_upload: array{max_size: int, max_parallel_count: int}}}
 	 */
 	public function getCapabilities(): array {
 		return [
diff --git a/apps/files/lib/Controller/DirectEditingController.php b/apps/files/lib/Controller/DirectEditingController.php
index 63f29d3ba2a..2c910006df5 100644
--- a/apps/files/lib/Controller/DirectEditingController.php
+++ b/apps/files/lib/Controller/DirectEditingController.php
@@ -36,7 +36,7 @@ class DirectEditingController extends OCSController {
 
 	/**
 	 * Get the direct editing capabilities
-	 * @return DataResponse<Http::STATUS_OK, array{editors: array<string, array{id: string, name: string, mimetypes: string[], optionalMimetypes: string[], secure: bool}>, creators: array<string, array{id: string, editor: string, name: string, extension: string, templates: bool, mimetypes: string[]}>}, array{}>
+	 * @return DataResponse<Http::STATUS_OK, array{editors: array<string, array{id: string, name: string, mimetypes: list<string>, optionalMimetypes: list<string>, secure: bool}>, creators: array<string, array{id: string, editor: string, name: string, extension: string, templates: bool, mimetypes: list<string>}>}, array{}>
 	 *
 	 * 200: Direct editing capabilities returned
 	 */
diff --git a/apps/files/lib/Controller/OpenLocalEditorController.php b/apps/files/lib/Controller/OpenLocalEditorController.php
index dae321ae437..b000304eef6 100644
--- a/apps/files/lib/Controller/OpenLocalEditorController.php
+++ b/apps/files/lib/Controller/OpenLocalEditorController.php
@@ -46,7 +46,7 @@ class OpenLocalEditorController extends OCSController {
 	 *
 	 * @param string $path Path of the file
 	 *
-	 * @return DataResponse<Http::STATUS_OK, array{userId: ?string, pathHash: string, expirationTime: int, token: string}, array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, array{userId: ?string, pathHash: string, expirationTime: int, token: string}, array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR, list<empty>, array{}>
 	 *
 	 * 200: Local editor returned
 	 */
@@ -91,7 +91,7 @@ class OpenLocalEditorController extends OCSController {
 	 * @param string $path Path of the file
 	 * @param string $token Token of the local editor
 	 *
-	 * @return DataResponse<Http::STATUS_OK, array{userId: string, pathHash: string, expirationTime: int, token: string}, array{}>|DataResponse<Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, array{userId: string, pathHash: string, expirationTime: int, token: string}, array{}>|DataResponse<Http::STATUS_NOT_FOUND, list<empty>, array{}>
 	 *
 	 * 200: Local editor validated successfully
 	 * 404: Local editor not found
diff --git a/apps/files/lib/Controller/TemplateController.php b/apps/files/lib/Controller/TemplateController.php
index 551c9c54c4b..3321fb5f119 100644
--- a/apps/files/lib/Controller/TemplateController.php
+++ b/apps/files/lib/Controller/TemplateController.php
@@ -16,13 +16,16 @@ use OCP\AppFramework\OCS\OCSForbiddenException;
 use OCP\AppFramework\OCSController;
 use OCP\Files\GenericFileException;
 use OCP\Files\Template\ITemplateManager;
+use OCP\Files\Template\Template;
 use OCP\Files\Template\TemplateFileCreator;
 use OCP\IRequest;
 
 /**
  * @psalm-import-type FilesTemplateFile from ResponseDefinitions
  * @psalm-import-type FilesTemplateFileCreator from ResponseDefinitions
+ * @psalm-import-type FilesTemplateFileCreatorWithTemplates from ResponseDefinitions
  * @psalm-import-type FilesTemplateField from ResponseDefinitions
+ * @psalm-import-type FilesTemplate from ResponseDefinitions
  */
 class TemplateController extends OCSController {
 	public function __construct(
@@ -36,13 +39,17 @@ class TemplateController extends OCSController {
 	/**
 	 * List the available templates
 	 *
-	 * @return DataResponse<Http::STATUS_OK, array<FilesTemplateFileCreator>, array{}>
+	 * @return DataResponse<Http::STATUS_OK, list<FilesTemplateFileCreatorWithTemplates>, array{}>
 	 *
 	 * 200: Available templates returned
 	 */
 	#[NoAdminRequired]
 	public function list(): DataResponse {
-		return new DataResponse($this->templateManager->listTemplates());
+		/* Convert embedded Template instances to arrays to match return type */
+		return new DataResponse(array_map(static function (array $templateFileCreator) {
+			$templateFileCreator['templates'] = array_map(static fn (Template $template) => $template->jsonSerialize(), $templateFileCreator['templates']);
+			return $templateFileCreator;
+		}, $this->templateManager->listTemplates()));
 	}
 
 	/**
@@ -51,7 +58,7 @@ class TemplateController extends OCSController {
 	 * @param string $filePath Path of the file
 	 * @param string $templatePath Name of the template
 	 * @param string $templateType Type of the template
-	 * @param FilesTemplateField[] $templateFields Fields of the template
+	 * @param list<FilesTemplateField> $templateFields Fields of the template
 	 *
 	 * @return DataResponse<Http::STATUS_OK, FilesTemplateFile, array{}>
 	 * @throws OCSForbiddenException Creating template is not allowed
@@ -82,7 +89,7 @@ class TemplateController extends OCSController {
 	 * @param string $templatePath Path of the template directory
 	 * @param bool $copySystemTemplates Whether to copy the system templates to the template directory
 	 *
-	 * @return DataResponse<Http::STATUS_OK, array{template_path: string, templates: FilesTemplateFileCreator[]}, array{}>
+	 * @return DataResponse<Http::STATUS_OK, array{template_path: string, templates: list<FilesTemplateFileCreator>}, array{}>
 	 * @throws OCSForbiddenException Initializing the template directory is not allowed
 	 *
 	 * 200: Template directory initialized successfully
@@ -94,7 +101,7 @@ class TemplateController extends OCSController {
 			$templatePath = $this->templateManager->initializeTemplateDirectory($templatePath, null, $copySystemTemplates);
 			return new DataResponse([
 				'template_path' => $templatePath,
-				'templates' => array_map(fn (TemplateFileCreator $creator) => $creator->jsonSerialize(), $this->templateManager->listCreators()),
+				'templates' => array_values(array_map(fn (TemplateFileCreator $creator) => $creator->jsonSerialize(), $this->templateManager->listCreators())),
 			]);
 		} catch (\Exception $e) {
 			throw new OCSForbiddenException($e->getMessage());
diff --git a/apps/files/lib/Controller/TransferOwnershipController.php b/apps/files/lib/Controller/TransferOwnershipController.php
index 1420e57e987..51a25400efb 100644
--- a/apps/files/lib/Controller/TransferOwnershipController.php
+++ b/apps/files/lib/Controller/TransferOwnershipController.php
@@ -47,7 +47,7 @@ class TransferOwnershipController extends OCSController {
 	 * @param string $recipient Username of the recipient
 	 * @param string $path Path of the file
 	 *
-	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN, list<empty>, array{}>
 	 *
 	 * 200: Ownership transferred successfully
 	 * 400: Transferring ownership is not possible
@@ -101,7 +101,7 @@ class TransferOwnershipController extends OCSController {
 	 *
 	 * @param int $id ID of the ownership transfer
 	 *
-	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, list<empty>, array{}>
 	 *
 	 * 200: Ownership transfer accepted successfully
 	 * 403: Accepting ownership transfer is not allowed
@@ -136,7 +136,7 @@ class TransferOwnershipController extends OCSController {
 	 *
 	 * @param int $id ID of the ownership transfer
 	 *
-	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 * @return DataResponse<Http::STATUS_OK|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, list<empty>, array{}>
 	 *
 	 * 200: Ownership transfer rejected successfully
 	 * 403: Rejecting ownership transfer is not allowed
diff --git a/apps/files/lib/Helper.php b/apps/files/lib/Helper.php
index ce33bbb80a6..b66dc9a2056 100644
--- a/apps/files/lib/Helper.php
+++ b/apps/files/lib/Helper.php
@@ -192,37 +192,34 @@ class Helper {
 	/**
 	 * Populate the result set with file tags
 	 *
-	 * @param array $fileList
-	 * @param string $fileIdentifier identifier attribute name for values in $fileList
-	 * @param ITagManager $tagManager
-	 * @return array file list populated with tags
+	 * @psalm-template T of array{tags?: list<string>, file_source: int, ...array<string, mixed>}
+	 * @param list<T> $fileList
+	 * @return list<T> file list populated with tags
 	 */
-	public static function populateTags(array $fileList, $fileIdentifier, ITagManager $tagManager) {
-		$ids = [];
-		foreach ($fileList as $fileData) {
-			$ids[] = $fileData[$fileIdentifier];
-		}
+	public static function populateTags(array $fileList, ITagManager $tagManager) {
 		$tagger = $tagManager->load('files');
-		$tags = $tagger->getTagsForObjects($ids);
+		$tags = $tagger->getTagsForObjects(array_map(static fn (array $fileData) => $fileData['file_source'], $fileList));
 
 		if (!is_array($tags)) {
 			throw new \UnexpectedValueException('$tags must be an array');
 		}
 
 		// Set empty tag array
-		foreach ($fileList as $key => $fileData) {
-			$fileList[$key]['tags'] = [];
+		foreach ($fileList as &$fileData) {
+			$fileData['tags'] = [];
 		}
+		unset($fileData);
 
 		if (!empty($tags)) {
 			foreach ($tags as $fileId => $fileTags) {
-				foreach ($fileList as $key => $fileData) {
-					if ($fileId !== $fileData[$fileIdentifier]) {
+				foreach ($fileList as &$fileData) {
+					if ($fileId !== $fileData['file_source']) {
 						continue;
 					}
 
-					$fileList[$key]['tags'] = $fileTags;
+					$fileData['tags'] = $fileTags;
 				}
+				unset($fileData);
 			}
 		}
 
diff --git a/apps/files/lib/ResponseDefinitions.php b/apps/files/lib/ResponseDefinitions.php
index a05cbb75b21..c5d094e7bd8 100644
--- a/apps/files/lib/ResponseDefinitions.php
+++ b/apps/files/lib/ResponseDefinitions.php
@@ -22,21 +22,45 @@ namespace OCA\Files;
  *     hasPreview: bool,
  * }
  *
+ * @psalm-type FilesTemplateField = array{
+ *     index: string,
+ *     type: string,
+ *     alias: ?string,
+ *     tag: ?string,
+ *     id: ?int,
+ *     content?: string,
+ *     checked?: bool,
+ * }
+ *
+ * @psalm-type FilesTemplate = array{
+ *      templateType: string,
+ *      templateId: string,
+ *      basename: string,
+ *      etag: string,
+ *      fileid: int,
+ *      filename: string,
+ *      lastmod: int,
+ *      mime: string,
+ *      size: int|float,
+ *      type: string,
+ *      hasPreview: bool,
+ *      previewUrl: ?string,
+ *      fields: list<FilesTemplateField>,
+ *  }
+ *
  * @psalm-type FilesTemplateFileCreator = array{
  *     app: string,
  *     label: string,
  *     extension: string,
  *     iconClass: ?string,
  *     iconSvgInline: ?string,
- *     mimetypes: string[],
+ *     mimetypes: list<string>,
  *     ratio: ?float,
  *     actionLabel: string,
  * }
  *
- * @psalm-type FilesTemplateField = array{
- *     index: string,
- *     content: string,
- *     type: string,
+ * @psalm-type FilesTemplateFileCreatorWithTemplates = FilesTemplateFileCreator&array{
+ *     templates: list<FilesTemplate>,
  * }
  *
  * @psalm-type FilesFolderTree = list<array{
diff --git a/apps/files/openapi.json b/apps/files/openapi.json
index ded6ebd95e2..2c33097438f 100644
--- a/apps/files/openapi.json
+++ b/apps/files/openapi.json
@@ -170,22 +170,114 @@
                     }
                 }
             },
+            "Template": {
+                "type": "object",
+                "required": [
+                    "templateType",
+                    "templateId",
+                    "basename",
+                    "etag",
+                    "fileid",
+                    "filename",
+                    "lastmod",
+                    "mime",
+                    "size",
+                    "type",
+                    "hasPreview",
+                    "previewUrl",
+                    "fields"
+                ],
+                "properties": {
+                    "templateType": {
+                        "type": "string"
+                    },
+                    "templateId": {
+                        "type": "string"
+                    },
+                    "basename": {
+                        "type": "string"
+                    },
+                    "etag": {
+                        "type": "string"
+                    },
+                    "fileid": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "filename": {
+                        "type": "string"
+                    },
+                    "lastmod": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "mime": {
+                        "type": "string"
+                    },
+                    "size": {
+                        "anyOf": [
+                            {
+                                "type": "integer",
+                                "format": "int64"
+                            },
+                            {
+                                "type": "number",
+                                "format": "double"
+                            }
+                        ]
+                    },
+                    "type": {
+                        "type": "string"
+                    },
+                    "hasPreview": {
+                        "type": "boolean"
+                    },
+                    "previewUrl": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "fields": {
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/TemplateField"
+                        }
+                    }
+                }
+            },
             "TemplateField": {
                 "type": "object",
                 "required": [
                     "index",
-                    "content",
-                    "type"
+                    "type",
+                    "alias",
+                    "tag",
+                    "id"
                 ],
                 "properties": {
                     "index": {
                         "type": "string"
                     },
-                    "content": {
+                    "type": {
                         "type": "string"
                     },
-                    "type": {
+                    "alias": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "tag": {
+                        "type": "string",
+                        "nullable": true
+                    },
+                    "id": {
+                        "type": "integer",
+                        "format": "int64",
+                        "nullable": true
+                    },
+                    "content": {
                         "type": "string"
+                    },
+                    "checked": {
+                        "type": "boolean"
                     }
                 }
             },
@@ -281,6 +373,27 @@
                         "type": "string"
                     }
                 }
+            },
+            "TemplateFileCreatorWithTemplates": {
+                "allOf": [
+                    {
+                        "$ref": "#/components/schemas/TemplateFileCreator"
+                    },
+                    {
+                        "type": "object",
+                        "required": [
+                            "templates"
+                        ],
+                        "properties": {
+                            "templates": {
+                                "type": "array",
+                                "items": {
+                                    "$ref": "#/components/schemas/Template"
+                                }
+                            }
+                        }
+                    }
+                ]
             }
         }
     },
@@ -1075,7 +1188,7 @@
                                                 "data": {
                                                     "type": "array",
                                                     "items": {
-                                                        "$ref": "#/components/schemas/TemplateFileCreator"
+                                                        "$ref": "#/components/schemas/TemplateFileCreatorWithTemplates"
                                                     }
                                                 }
                                             }
diff --git a/apps/files/tests/HelperTest.php b/apps/files/tests/HelperTest.php
index 27b1de1322f..0cf2812f816 100644
--- a/apps/files/tests/HelperTest.php
+++ b/apps/files/tests/HelperTest.php
@@ -104,9 +104,9 @@ class HelperTest extends \Test\TestCase {
 			->willReturn($tagger);
 
 		$data = [
-			['id' => 10],
-			['id' => 22, 'foo' => 'bar'],
-			['id' => 42, 'x' => 'y'],
+			['file_source' => 10],
+			['file_source' => 22, 'foo' => 'bar'],
+			['file_source' => 42, 'x' => 'y'],
 		];
 
 		$tags = [
@@ -118,12 +118,12 @@ class HelperTest extends \Test\TestCase {
 			->with([10, 22, 42])
 			->willReturn($tags);
 
-		$result = Helper::populateTags($data, 'id', $tagManager);
+		$result = Helper::populateTags($data, $tagManager);
 
 		$this->assertSame([
-			['id' => 10, 'tags' => ['tag3']],
-			['id' => 22, 'foo' => 'bar', 'tags' => []],
-			['id' => 42, 'x' => 'y', 'tags' => ['tag1', 'tag2']],
+			['file_source' => 10, 'tags' => ['tag3']],
+			['file_source' => 22, 'foo' => 'bar', 'tags' => []],
+			['file_source' => 42, 'x' => 'y', 'tags' => ['tag1', 'tag2']],
 		], $result);
 	}
 }