From 259264b966b3fde0cfcfb44e8047206c58917268 Mon Sep 17 00:00:00 2001 From: jld3103 Date: Wed, 14 Jun 2023 14:43:41 +0200 Subject: [PATCH] files: Add OpenAPI spec Signed-off-by: jld3103 --- .../composer/composer/autoload_classmap.php | 1 + .../composer/composer/autoload_static.php | 1 + apps/files/lib/Capabilities.php | 4 +- apps/files/lib/Controller/ApiController.php | 18 +- .../Controller/DirectEditingController.php | 35 + .../DirectEditingViewController.php | 2 + .../Controller/OpenLocalEditorController.php | 18 + .../lib/Controller/TemplateController.php | 37 +- .../TransferOwnershipController.php | 31 + apps/files/lib/Controller/ViewController.php | 5 +- apps/files/lib/DirectEditingCapabilities.php | 3 + apps/files/lib/ResponseDefinitions.php | 67 + apps/files/openapi.json | 1904 +++++++++++++++++ .../Files/Template/TemplateFileCreator.php | 4 + 14 files changed, 2120 insertions(+), 10 deletions(-) create mode 100644 apps/files/lib/ResponseDefinitions.php create mode 100644 apps/files/openapi.json diff --git a/apps/files/composer/composer/autoload_classmap.php b/apps/files/composer/composer/autoload_classmap.php index 88d3ae104137e..e4f3ff5b6351d 100644 --- a/apps/files/composer/composer/autoload_classmap.php +++ b/apps/files/composer/composer/autoload_classmap.php @@ -61,6 +61,7 @@ 'OCA\\Files\\Migration\\Version11301Date20191205150729' => $baseDir . '/../lib/Migration/Version11301Date20191205150729.php', 'OCA\\Files\\Migration\\Version12101Date20221011153334' => $baseDir . '/../lib/Migration/Version12101Date20221011153334.php', 'OCA\\Files\\Notification\\Notifier' => $baseDir . '/../lib/Notification/Notifier.php', + 'OCA\\Files\\ResponseDefinitions' => $baseDir . '/../lib/ResponseDefinitions.php', 'OCA\\Files\\Search\\FilesSearchProvider' => $baseDir . '/../lib/Search/FilesSearchProvider.php', 'OCA\\Files\\Service\\DirectEditingService' => $baseDir . '/../lib/Service/DirectEditingService.php', 'OCA\\Files\\Service\\OwnershipTransferService' => $baseDir . '/../lib/Service/OwnershipTransferService.php', diff --git a/apps/files/composer/composer/autoload_static.php b/apps/files/composer/composer/autoload_static.php index c27db581e610f..a844183e4fc17 100644 --- a/apps/files/composer/composer/autoload_static.php +++ b/apps/files/composer/composer/autoload_static.php @@ -76,6 +76,7 @@ class ComposerStaticInitFiles 'OCA\\Files\\Migration\\Version11301Date20191205150729' => __DIR__ . '/..' . '/../lib/Migration/Version11301Date20191205150729.php', 'OCA\\Files\\Migration\\Version12101Date20221011153334' => __DIR__ . '/..' . '/../lib/Migration/Version12101Date20221011153334.php', 'OCA\\Files\\Notification\\Notifier' => __DIR__ . '/..' . '/../lib/Notification/Notifier.php', + 'OCA\\Files\\ResponseDefinitions' => __DIR__ . '/..' . '/../lib/ResponseDefinitions.php', 'OCA\\Files\\Search\\FilesSearchProvider' => __DIR__ . '/..' . '/../lib/Search/FilesSearchProvider.php', 'OCA\\Files\\Service\\DirectEditingService' => __DIR__ . '/..' . '/../lib/Service/DirectEditingService.php', 'OCA\\Files\\Service\\OwnershipTransferService' => __DIR__ . '/..' . '/../lib/Service/OwnershipTransferService.php', diff --git a/apps/files/lib/Capabilities.php b/apps/files/lib/Capabilities.php index 5cb976a47be0b..dc2aae6acfcd9 100644 --- a/apps/files/lib/Capabilities.php +++ b/apps/files/lib/Capabilities.php @@ -38,12 +38,14 @@ public function __construct(IConfig $config) { /** * Return this classes capabilities + * + * @return array{files: array{bigfilechunking: bool, blacklisted_files: array}} */ public function getCapabilities() { return [ 'files' => [ 'bigfilechunking' => true, - 'blacklisted_files' => $this->config->getSystemValue('blacklisted_files', ['.htaccess']) + 'blacklisted_files' => (array)$this->config->getSystemValue('blacklisted_files', ['.htaccess']) ], ]; } diff --git a/apps/files/lib/Controller/ApiController.php b/apps/files/lib/Controller/ApiController.php index f8911c4d10425..3d490f06b75b2 100644 --- a/apps/files/lib/Controller/ApiController.php +++ b/apps/files/lib/Controller/ApiController.php @@ -60,8 +60,6 @@ use OCP\Share\IShare; /** - * Class ApiController - * * @package OCA\Files\Controller */ class ApiController extends Controller { @@ -104,10 +102,14 @@ public function __construct(string $appName, * @NoCSRFRequired * @StrictCookieRequired * - * @param int $x - * @param int $y + * @param int $x Width of the thumbnail + * @param int $y Height of the thumbnail * @param string $file URL-encoded filename - * @return DataResponse|FileDisplayResponse + * @return FileDisplayResponse|DataResponse + * + * 200: Thumbnail returned + * 400: Getting thumbnail is not possible + * 404: File not found */ public function getThumbnail($x, $y, $file) { if ($x < 1 || $y < 1) { @@ -386,6 +388,12 @@ public function getGridView() { /** * @NoAdminRequired * @NoCSRFRequired + * + * Get the service-worker Javascript for previews + * + * @psalm-suppress MoreSpecificReturnType The value of Service-Worker-Allowed is not relevant + * @psalm-suppress LessSpecificReturnStatement The value of Service-Worker-Allowed is not relevant + * @return StreamResponse */ public function serviceWorker(): StreamResponse { $response = new StreamResponse(__DIR__ . '/../../../../dist/preview-service-worker.js'); diff --git a/apps/files/lib/Controller/DirectEditingController.php b/apps/files/lib/Controller/DirectEditingController.php index 9b48d6958aa8a..d58be166e797d 100644 --- a/apps/files/lib/Controller/DirectEditingController.php +++ b/apps/files/lib/Controller/DirectEditingController.php @@ -63,6 +63,9 @@ public function __construct($appName, IRequest $request, $corsMethods, $corsAllo /** * @NoAdminRequired + * + * Get the direct editing capabilities + * @return DataResponse, creators: array}, array{}> */ public function info(): DataResponse { $response = new DataResponse($this->directEditingService->getDirectEditingCapabilitites()); @@ -72,6 +75,18 @@ public function info(): DataResponse { /** * @NoAdminRequired + * + * Create a file for direct editing + * + * @param string $path Path of the file + * @param string $editorId ID of the editor + * @param string $creatorId ID of the creator + * @param ?string $templateId ID of the template + * + * @return DataResponse|DataResponse + * + * 200: URL for direct editing returned + * 403: Opening file is not allowed */ public function create(string $path, string $editorId, string $creatorId, string $templateId = null): DataResponse { if (!$this->directEditingManager->isEnabled()) { @@ -92,6 +107,17 @@ public function create(string $path, string $editorId, string $creatorId, string /** * @NoAdminRequired + * + * Open a file for direct editing + * + * @param string $path Path of the file + * @param ?string $editorId ID of the editor + * @param ?int $fileId ID of the file + * + * @return DataResponse|DataResponse + * + * 200: URL for direct editing returned + * 403: Opening file is not allowed */ public function open(string $path, string $editorId = null, ?int $fileId = null): DataResponse { if (!$this->directEditingManager->isEnabled()) { @@ -114,6 +140,15 @@ public function open(string $path, string $editorId = null, ?int $fileId = null) /** * @NoAdminRequired + * + * Get the templates for direct editing + * + * @param string $editorId ID of the editor + * @param string $creatorId ID of the creator + * + * @return DataResponse}, array{}>|DataResponse + * + * 200: Templates returned */ public function templates(string $editorId, string $creatorId): DataResponse { if (!$this->directEditingManager->isEnabled()) { diff --git a/apps/files/lib/Controller/DirectEditingViewController.php b/apps/files/lib/Controller/DirectEditingViewController.php index 30d54d5ceb366..0741b58cfe9d4 100644 --- a/apps/files/lib/Controller/DirectEditingViewController.php +++ b/apps/files/lib/Controller/DirectEditingViewController.php @@ -24,6 +24,7 @@ use Exception; use OCP\AppFramework\Controller; +use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI; use OCP\AppFramework\Http\NotFoundResponse; use OCP\AppFramework\Http\Response; use OCP\DirectEditing\IManager; @@ -32,6 +33,7 @@ use OCP\ILogger; use OCP\IRequest; +#[IgnoreOpenAPI] class DirectEditingViewController extends Controller { /** @var IEventDispatcher */ diff --git a/apps/files/lib/Controller/OpenLocalEditorController.php b/apps/files/lib/Controller/OpenLocalEditorController.php index 7d784196361c1..d9fb80f2d2b61 100644 --- a/apps/files/lib/Controller/OpenLocalEditorController.php +++ b/apps/files/lib/Controller/OpenLocalEditorController.php @@ -70,6 +70,14 @@ public function __construct( /** * @NoAdminRequired * @UserRateThrottle(limit=10, period=120) + * + * Create a local editor + * + * @param string $path Path of the file + * + * @return DataResponse|DataResponse, array{}> + * + * 200: Local editor returned */ public function create(string $path): DataResponse { $pathHash = sha1($path); @@ -107,6 +115,16 @@ public function create(string $path): DataResponse { /** * @NoAdminRequired * @BruteForceProtection(action=openLocalEditor) + * + * Validate a local editor + * + * @param string $path Path of the file + * @param string $token Token of the local editor + * + * @return DataResponse|DataResponse, array{}> + * + * 200: Local editor validated successfully + * 404: Local editor not found */ public function validate(string $path, string $token): DataResponse { $pathHash = sha1($path); diff --git a/apps/files/lib/Controller/TemplateController.php b/apps/files/lib/Controller/TemplateController.php index d04d86760e629..645350010eccb 100644 --- a/apps/files/lib/Controller/TemplateController.php +++ b/apps/files/lib/Controller/TemplateController.php @@ -26,13 +26,21 @@ */ namespace OCA\Files\Controller; +use OCA\Files\ResponseDefinitions; +use OCP\AppFramework\Http; use OCP\AppFramework\Http\DataResponse; use OCP\AppFramework\OCS\OCSForbiddenException; use OCP\AppFramework\OCSController; use OCP\Files\GenericFileException; use OCP\Files\Template\ITemplateManager; +use OCP\Files\Template\TemplateFileCreator; use OCP\IRequest; +/** + * @psalm-import-type FilesTemplate from ResponseDefinitions + * @psalm-import-type FilesTemplateFile from ResponseDefinitions + * @psalm-import-type FilesTemplateFileCreator from ResponseDefinitions + */ class TemplateController extends OCSController { protected $templateManager; @@ -43,6 +51,10 @@ public function __construct($appName, IRequest $request, ITemplateManager $templ /** * @NoAdminRequired + * + * List the available templates + * + * @return DataResponse, array{}> */ public function list(): DataResponse { return new DataResponse($this->templateManager->listTemplates()); @@ -50,7 +62,17 @@ public function list(): DataResponse { /** * @NoAdminRequired - * @throws OCSForbiddenException + * + * Create a template + * + * @param string $filePath Path of the file + * @param string $templatePath Name of the template + * @param string $templateType Type of the template + * + * @return DataResponse + * @throws OCSForbiddenException Creating template is not allowed + * + * 200: Template created successfully */ public function create(string $filePath, string $templatePath = '', string $templateType = 'user'): DataResponse { try { @@ -62,13 +84,24 @@ public function create(string $filePath, string $templatePath = '', string $temp /** * @NoAdminRequired + * + * Initialize the template directory + * + * @param string $templatePath Path of the template directory + * @param bool $copySystemTemplates Whether to copy the system templates to the template directory + * + * @return DataResponse + * @throws OCSForbiddenException Initializing the template directory is not allowed + * + * 200: Template directory initialized successfully */ public function path(string $templatePath = '', bool $copySystemTemplates = false) { try { + /** @var string $templatePath */ $templatePath = $this->templateManager->initializeTemplateDirectory($templatePath, null, $copySystemTemplates); return new DataResponse([ 'template_path' => $templatePath, - 'templates' => $this->templateManager->listCreators() + 'templates' => 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 5abd65444bf99..ce68b28349e7e 100644 --- a/apps/files/lib/Controller/TransferOwnershipController.php +++ b/apps/files/lib/Controller/TransferOwnershipController.php @@ -82,6 +82,17 @@ public function __construct(string $appName, /** * @NoAdminRequired + * + * Transfer the ownership to another user + * + * @param string $recipient Username of the recipient + * @param string $path Path of the file + * + * @return DataResponse, array{}> + * + * 200: Ownership transferred successfully + * 400: Transferring ownership is not possible + * 403: Transferring ownership is not allowed */ public function transfer(string $recipient, string $path): DataResponse { $recipientUser = $this->userManager->get($recipient); @@ -127,6 +138,16 @@ public function transfer(string $recipient, string $path): DataResponse { /** * @NoAdminRequired + * + * Accept an ownership transfer + * + * @param int $id ID of the ownership transfer + * + * @return DataResponse, array{}> + * + * 200: Ownership transfer accepted successfully + * 403: Accepting ownership transfer is not allowed + * 404: Ownership transfer not found */ public function accept(int $id): DataResponse { try { @@ -160,6 +181,16 @@ public function accept(int $id): DataResponse { /** * @NoAdminRequired + * + * Reject an ownership transfer + * + * @param int $id ID of the ownership transfer + * + * @return DataResponse, array{}> + * + * 200: Ownership transfer rejected successfully + * 403: Rejecting ownership transfer is not allowed + * 404: Ownership transfer not found */ public function reject(int $id): DataResponse { try { diff --git a/apps/files/lib/Controller/ViewController.php b/apps/files/lib/Controller/ViewController.php index 43be43aa11647..01f85a7c93971 100644 --- a/apps/files/lib/Controller/ViewController.php +++ b/apps/files/lib/Controller/ViewController.php @@ -35,6 +35,7 @@ */ namespace OCA\Files\Controller; +use OC\AppFramework\Http; use OCA\Files\Activity\Helper; use OCA\Files\AppInfo\Application; use OCA\Files\Event\LoadAdditionalScriptsEvent; @@ -44,6 +45,7 @@ use OCA\Viewer\Event\LoadViewer; use OCP\App\IAppManager; use OCP\AppFramework\Controller; +use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI; use OCP\AppFramework\Http\ContentSecurityPolicy; use OCP\AppFramework\Http\RedirectResponse; use OCP\AppFramework\Http\Response; @@ -63,10 +65,9 @@ use OCP\Share\IManager; /** - * Class ViewController - * * @package OCA\Files\Controller */ +#[IgnoreOpenAPI] class ViewController extends Controller { private IURLGenerator $urlGenerator; private IL10N $l10n; diff --git a/apps/files/lib/DirectEditingCapabilities.php b/apps/files/lib/DirectEditingCapabilities.php index 10c8e95105a31..1bc00519ae85e 100644 --- a/apps/files/lib/DirectEditingCapabilities.php +++ b/apps/files/lib/DirectEditingCapabilities.php @@ -38,6 +38,9 @@ public function __construct(DirectEditingService $directEditingService, IURLGene $this->urlGenerator = $urlGenerator; } + /** + * @return array{files: array{directEditing: array{url: string, etag: string, supportsFileId: bool}}} + */ public function getCapabilities() { return [ 'files' => [ diff --git a/apps/files/lib/ResponseDefinitions.php b/apps/files/lib/ResponseDefinitions.php new file mode 100644 index 0000000000000..8a27ec4bb2fc6 --- /dev/null +++ b/apps/files/lib/ResponseDefinitions.php @@ -0,0 +1,67 @@ + + * + * @author Kate Döen + * + * @license GNU AGPL version 3 or any later version + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as + * published by the Free Software Foundation, either version 3 of the + * License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see . + * + */ + +namespace OCA\Files; + +/** + * @psalm-type FilesTemplate = array{ + * templateType: string, + * templateId: string, + * basename: string, + * etag: string, + * fileid: int, + * filename: string, + * lastmod: int, + * mime: string, + * size: int, + * type: string, + * hasPreview: bool, + * previewUrl: ?string, + * } + * + * @psalm-type FilesTemplateFile = array{ + * basename: string, + * etag: string, + * fileid: int, + * filename: ?string, + * lastmod: int, + * mime: string, + * size: int, + * type: string, + * hasPreview: bool, + * } + * + * @psalm-type FilesTemplateFileCreator = array{ + * app: string, + * label: string, + * extension: string, + * iconClass: ?string, + * mimetypes: string[], + * ratio: ?float, + * actionLabel: string, + * } + */ +class ResponseDefinitions { +} diff --git a/apps/files/openapi.json b/apps/files/openapi.json new file mode 100644 index 0000000000000..c8e9bb6ff41fa --- /dev/null +++ b/apps/files/openapi.json @@ -0,0 +1,1904 @@ +{ + "openapi": "3.0.3", + "info": { + "title": "files", + "version": "0.0.1", + "description": "File Management", + "license": { + "name": "agpl" + } + }, + "components": { + "securitySchemes": { + "basic_auth": { + "type": "http", + "scheme": "basic" + }, + "bearer_auth": { + "type": "http", + "scheme": "bearer" + } + }, + "schemas": { + "Capabilities": { + "type": "object", + "properties": { + "files": { + "type": [ + "object", + "object" + ], + "required": [ + "bigfilechunking", + "blacklisted_files", + "directEditing" + ], + "properties": { + "bigfilechunking": { + "type": "boolean" + }, + "blacklisted_files": { + "type": "array", + "items": { + "type": "object" + } + }, + "directEditing": { + "type": "object", + "required": [ + "url", + "etag", + "supportsFileId" + ], + "properties": { + "url": { + "type": "string" + }, + "etag": { + "type": "string" + }, + "supportsFileId": { + "type": "boolean" + } + } + } + } + } + } + }, + "OCSMeta": { + "type": "object", + "required": [ + "status", + "statuscode" + ], + "properties": { + "status": { + "type": "string" + }, + "statuscode": { + "type": "integer" + }, + "message": { + "type": "string" + }, + "totalitems": { + "type": "string" + }, + "itemsperpage": { + "type": "string" + } + } + }, + "Template": { + "type": "object", + "required": [ + "templateType", + "templateId", + "basename", + "etag", + "fileid", + "filename", + "lastmod", + "mime", + "size", + "type", + "hasPreview", + "previewUrl" + ], + "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": { + "type": "integer", + "format": "int64" + }, + "type": { + "type": "string" + }, + "hasPreview": { + "type": "boolean" + }, + "previewUrl": { + "type": "string", + "nullable": true + } + } + }, + "TemplateFile": { + "type": "object", + "required": [ + "basename", + "etag", + "fileid", + "filename", + "lastmod", + "mime", + "size", + "type", + "hasPreview" + ], + "properties": { + "basename": { + "type": "string" + }, + "etag": { + "type": "string" + }, + "fileid": { + "type": "integer", + "format": "int64" + }, + "filename": { + "type": "string", + "nullable": true + }, + "lastmod": { + "type": "integer", + "format": "int64" + }, + "mime": { + "type": "string" + }, + "size": { + "type": "integer", + "format": "int64" + }, + "type": { + "type": "string" + }, + "hasPreview": { + "type": "boolean" + } + } + }, + "TemplateFileCreator": { + "type": "object", + "required": [ + "app", + "label", + "extension", + "iconClass", + "mimetypes", + "ratio", + "actionLabel" + ], + "properties": { + "app": { + "type": "string" + }, + "label": { + "type": "string" + }, + "extension": { + "type": "string" + }, + "iconClass": { + "type": "string", + "nullable": true + }, + "mimetypes": { + "type": "array", + "items": { + "type": "string" + } + }, + "ratio": { + "type": "number", + "format": "float", + "nullable": true + }, + "actionLabel": { + "type": "string" + } + } + } + } + }, + "paths": { + "/index.php/apps/files/api/v1/thumbnail/{x}/{y}/{file}": { + "get": { + "operationId": "api-get-thumbnail", + "summary": "Gets a thumbnail of the specified file", + "tags": [ + "api" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "x", + "in": "path", + "description": "Width of the thumbnail", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "y", + "in": "path", + "description": "Height of the thumbnail", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "file", + "in": "path", + "description": "URL-encoded filename", + "required": true, + "schema": { + "type": "string", + "pattern": "^.+$" + } + } + ], + "responses": { + "200": { + "description": "Thumbnail returned", + "content": { + "*/*": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + }, + "400": { + "description": "Getting thumbnail is not possible", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string" + } + } + } + } + } + }, + "404": { + "description": "File not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string" + } + } + } + } + } + } + } + } + }, + "/index.php/apps/files/preview-service-worker.js": { + "get": { + "operationId": "api-service-worker", + "summary": "Get the service-worker Javascript for previews", + "tags": [ + "api" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "responses": { + "200": { + "description": "", + "headers": { + "Service-Worker-Allowed": { + "schema": { + "type": "string" + } + } + }, + "content": { + "application/javascript": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/files/api/v1/directEditing": { + "get": { + "operationId": "direct_editing-info", + "summary": "Get the direct editing capabilities", + "tags": [ + "direct_editing" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "object", + "required": [ + "editors", + "creators" + ], + "properties": { + "editors": { + "type": "object", + "additionalProperties": { + "type": "object", + "required": [ + "id", + "name", + "mimetypes", + "optionalMimetypes", + "secure" + ], + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "mimetypes": { + "type": "array", + "items": { + "type": "string" + } + }, + "optionalMimetypes": { + "type": "array", + "items": { + "type": "string" + } + }, + "secure": { + "type": "boolean" + } + } + } + }, + "creators": { + "type": "object", + "additionalProperties": { + "type": "object", + "required": [ + "id", + "editor", + "name", + "extension", + "templates", + "mimetypes" + ], + "properties": { + "id": { + "type": "string" + }, + "editor": { + "type": "string" + }, + "name": { + "type": "string" + }, + "extension": { + "type": "string" + }, + "templates": { + "type": "boolean" + }, + "mimetypes": { + "type": "array", + "items": { + "type": "string" + } + } + } + } + } + } + } + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/files/api/v1/directEditing/templates/{editorId}/{creatorId}": { + "get": { + "operationId": "direct_editing-templates", + "summary": "Get the templates for direct editing", + "tags": [ + "direct_editing" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "editorId", + "in": "path", + "description": "ID of the editor", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "creatorId", + "in": "path", + "description": "ID of the creator", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "Templates returned", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "object", + "required": [ + "templates" + ], + "properties": { + "templates": { + "type": "object", + "additionalProperties": { + "type": "object", + "required": [ + "id", + "title", + "preview", + "extension", + "mimetype" + ], + "properties": { + "id": { + "type": "string" + }, + "title": { + "type": "string" + }, + "preview": { + "type": "string", + "nullable": true + }, + "extension": { + "type": "string" + }, + "mimetype": { + "type": "string" + } + } + } + } + } + } + } + } + } + } + } + } + }, + "500": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "object", + "required": [ + "message" + ], + "properties": { + "message": { + "type": "string" + } + } + } + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/files/api/v1/directEditing/open": { + "post": { + "operationId": "direct_editing-open", + "summary": "Open a file for direct editing", + "tags": [ + "direct_editing" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "path", + "in": "query", + "description": "Path of the file", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "editorId", + "in": "query", + "description": "ID of the editor", + "schema": { + "type": "string", + "nullable": true + } + }, + { + "name": "fileId", + "in": "query", + "description": "ID of the file", + "schema": { + "type": "integer", + "format": "int64", + "nullable": true + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "URL for direct editing returned", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "object", + "required": [ + "url" + ], + "properties": { + "url": { + "type": "string" + } + } + } + } + } + } + } + } + } + }, + "403": { + "description": "Opening file is not allowed", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "object", + "required": [ + "message" + ], + "properties": { + "message": { + "type": "string" + } + } + } + } + } + } + } + } + } + }, + "500": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "object", + "required": [ + "message" + ], + "properties": { + "message": { + "type": "string" + } + } + } + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/files/api/v1/directEditing/create": { + "post": { + "operationId": "direct_editing-create", + "summary": "Create a file for direct editing", + "tags": [ + "direct_editing" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "path", + "in": "query", + "description": "Path of the file", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "editorId", + "in": "query", + "description": "ID of the editor", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "creatorId", + "in": "query", + "description": "ID of the creator", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "templateId", + "in": "query", + "description": "ID of the template", + "schema": { + "type": "string", + "nullable": true + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "URL for direct editing returned", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "object", + "required": [ + "url" + ], + "properties": { + "url": { + "type": "string" + } + } + } + } + } + } + } + } + } + }, + "403": { + "description": "Opening file is not allowed", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "object", + "required": [ + "message" + ], + "properties": { + "message": { + "type": "string" + } + } + } + } + } + } + } + } + } + }, + "500": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "object", + "required": [ + "message" + ], + "properties": { + "message": { + "type": "string" + } + } + } + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/files/api/v1/templates": { + "get": { + "operationId": "template-list", + "summary": "List the available templates", + "tags": [ + "template" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TemplateFileCreator" + } + } + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/files/api/v1/templates/create": { + "post": { + "operationId": "template-create", + "summary": "Create a template", + "tags": [ + "template" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "filePath", + "in": "query", + "description": "Path of the file", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "templatePath", + "in": "query", + "description": "Name of the template", + "schema": { + "type": "string", + "default": "" + } + }, + { + "name": "templateType", + "in": "query", + "description": "Type of the template", + "schema": { + "type": "string", + "default": "user" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "Template created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "$ref": "#/components/schemas/TemplateFile" + } + } + } + } + } + } + } + }, + "403": { + "description": "Creating template is not allowed", + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/files/api/v1/templates/path": { + "post": { + "operationId": "template-path", + "summary": "Initialize the template directory", + "tags": [ + "template" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "templatePath", + "in": "query", + "description": "Path of the template directory", + "schema": { + "type": "string", + "default": "" + } + }, + { + "name": "copySystemTemplates", + "in": "query", + "description": "Whether to copy the system templates to the template directory", + "schema": { + "type": "integer", + "default": 0 + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "Template directory initialized successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "object", + "required": [ + "template_path", + "templates" + ], + "properties": { + "template_path": { + "type": "string" + }, + "templates": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TemplateFileCreator" + } + } + } + } + } + } + } + } + } + } + }, + "403": { + "description": "Initializing the template directory is not allowed", + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/files/api/v1/transferownership": { + "post": { + "operationId": "transfer_ownership-transfer", + "summary": "Transfer the ownership to another user", + "tags": [ + "transfer_ownership" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "recipient", + "in": "query", + "description": "Username of the recipient", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "path", + "in": "query", + "description": "Path of the file", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "Ownership transferred successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "400": { + "description": "Transferring ownership is not possible", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Transferring ownership is not allowed", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/files/api/v1/transferownership/{id}": { + "post": { + "operationId": "transfer_ownership-accept", + "summary": "Accept an ownership transfer", + "tags": [ + "transfer_ownership" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "ID of the ownership transfer", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "Ownership transfer accepted successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Accepting ownership transfer is not allowed", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "404": { + "description": "Ownership transfer not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + }, + "delete": { + "operationId": "transfer_ownership-reject", + "summary": "Reject an ownership transfer", + "tags": [ + "transfer_ownership" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "description": "ID of the ownership transfer", + "required": true, + "schema": { + "type": "integer", + "format": "int64" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "Ownership transfer rejected successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "403": { + "description": "Rejecting ownership transfer is not allowed", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + }, + "404": { + "description": "Ownership transfer not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/files/api/v1/openlocaleditor": { + "post": { + "operationId": "open_local_editor-create", + "summary": "Create a local editor", + "tags": [ + "open_local_editor" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "path", + "in": "query", + "description": "Path of the file", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "Local editor returned", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "object", + "required": [ + "userId", + "pathHash", + "expirationTime", + "token" + ], + "properties": { + "userId": { + "type": "string", + "nullable": true + }, + "pathHash": { + "type": "string" + }, + "expirationTime": { + "type": "integer", + "format": "int64" + }, + "token": { + "type": "string" + } + } + } + } + } + } + } + } + } + }, + "500": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + }, + "/ocs/v2.php/apps/files/api/v1/openlocaleditor/{token}": { + "post": { + "operationId": "open_local_editor-validate", + "summary": "Validate a local editor", + "tags": [ + "open_local_editor" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "path", + "in": "query", + "description": "Path of the file", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "token", + "in": "path", + "description": "Token of the local editor", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "Local editor validated successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "object", + "required": [ + "userId", + "pathHash", + "expirationTime", + "token" + ], + "properties": { + "userId": { + "type": "string" + }, + "pathHash": { + "type": "string" + }, + "expirationTime": { + "type": "integer", + "format": "int64" + }, + "token": { + "type": "string" + } + } + } + } + } + } + } + } + } + }, + "404": { + "description": "Local editor not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": {} + } + } + } + } + } + } + } + } + } + } + }, + "tags": [] +} \ No newline at end of file diff --git a/lib/public/Files/Template/TemplateFileCreator.php b/lib/public/Files/Template/TemplateFileCreator.php index 3a1e62c6f5c55..43e96b6f21b9c 100644 --- a/lib/public/Files/Template/TemplateFileCreator.php +++ b/lib/public/Files/Template/TemplateFileCreator.php @@ -31,10 +31,13 @@ */ final class TemplateFileCreator implements \JsonSerializable { protected $appId; + /** @var string[] $mimetypes */ protected $mimetypes = []; protected $actionName; protected $fileExtension; + /** @var ?string $iconClass */ protected $iconClass; + /** @var ?float $ratio */ protected $ratio = null; protected $order = 100; /** @@ -124,6 +127,7 @@ public function getActionLabel(): string { /** * @since 21.0.0 + * @return array{app: string, label: string, extension: string, iconClass: ?string, mimetypes: string[], ratio: ?float, actionLabel: string} */ public function jsonSerialize(): array { return [