diff options
Diffstat (limited to 'apps/files/lib/Controller')
7 files changed, 137 insertions, 9 deletions
diff --git a/apps/files/lib/Controller/ApiController.php b/apps/files/lib/Controller/ApiController.php index f8911c4d104..3d490f06b75 100644 --- a/apps/files/lib/Controller/ApiController.php +++ b/apps/files/lib/Controller/ApiController.php @@ -60,8 +60,6 @@ use OCP\Share\IManager; use OCP\Share\IShare; /** - * Class ApiController - * * @package OCA\Files\Controller */ class ApiController extends Controller { @@ -104,10 +102,14 @@ class ApiController extends Controller { * @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<Http::STATUS_OK, array{Content-Type: string}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_NOT_FOUND, array{message?: string}, array{}> + * + * 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 @@ class ApiController extends Controller { /** * @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<Http::STATUS_OK, array{Content-Type: 'application/javascript', Service-Worker-Allowed: string}> */ 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 9b48d6958aa..d58be166e79 100644 --- a/apps/files/lib/Controller/DirectEditingController.php +++ b/apps/files/lib/Controller/DirectEditingController.php @@ -63,6 +63,9 @@ class DirectEditingController extends OCSController { /** * @NoAdminRequired + * + * 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{}> */ public function info(): DataResponse { $response = new DataResponse($this->directEditingService->getDirectEditingCapabilitites()); @@ -72,6 +75,18 @@ class DirectEditingController extends OCSController { /** * @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<Http::STATUS_OK, array{url: string}, array{}>|DataResponse<Http::STATUS_FORBIDDEN|Http::STATUS_INTERNAL_SERVER_ERROR, array{message: string}, array{}> + * + * 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 @@ class DirectEditingController extends OCSController { /** * @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<Http::STATUS_OK, array{url: string}, array{}>|DataResponse<Http::STATUS_FORBIDDEN|Http::STATUS_INTERNAL_SERVER_ERROR, array{message: string}, array{}> + * + * 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 @@ class DirectEditingController extends OCSController { /** * @NoAdminRequired + * + * Get the templates for direct editing + * + * @param string $editorId ID of the editor + * @param string $creatorId ID of the creator + * + * @return DataResponse<Http::STATUS_OK, array{templates: array<string, array{id: string, title: string, preview: ?string, extension: string, mimetype: string}>}, array{}>|DataResponse<Http::STATUS_INTERNAL_SERVER_ERROR, array{message: string}, array{}> + * + * 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 30d54d5ceb3..0741b58cfe9 100644 --- a/apps/files/lib/Controller/DirectEditingViewController.php +++ b/apps/files/lib/Controller/DirectEditingViewController.php @@ -24,6 +24,7 @@ namespace OCA\Files\Controller; 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\EventDispatcher\IEventDispatcher; 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 7d784196361..d9fb80f2d2b 100644 --- a/apps/files/lib/Controller/OpenLocalEditorController.php +++ b/apps/files/lib/Controller/OpenLocalEditorController.php @@ -70,6 +70,14 @@ class OpenLocalEditorController extends OCSController { /** * @NoAdminRequired * @UserRateThrottle(limit=10, period=120) + * + * Create a local editor + * + * @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{}> + * + * 200: Local editor returned */ public function create(string $path): DataResponse { $pathHash = sha1($path); @@ -107,6 +115,16 @@ class OpenLocalEditorController extends OCSController { /** * @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<Http::STATUS_OK, array{userId: string, pathHash: string, expirationTime: int, token: string}, array{}>|DataResponse<Http::STATUS_NOT_FOUND, array<empty>, 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 d04d86760e6..645350010ec 100644 --- a/apps/files/lib/Controller/TemplateController.php +++ b/apps/files/lib/Controller/TemplateController.php @@ -26,13 +26,21 @@ declare(strict_types=1); */ 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 @@ class TemplateController extends OCSController { /** * @NoAdminRequired + * + * List the available templates + * + * @return DataResponse<Http::STATUS_OK, array<FilesTemplateFileCreator>, array{}> */ public function list(): DataResponse { return new DataResponse($this->templateManager->listTemplates()); @@ -50,7 +62,17 @@ class TemplateController extends OCSController { /** * @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<Http::STATUS_OK, FilesTemplateFile, array{}> + * @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 @@ class TemplateController extends OCSController { /** * @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<Http::STATUS_OK, array{template_path: string, templates: FilesTemplateFileCreator[]}, array{}> + * @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 5abd65444bf..ce68b28349e 100644 --- a/apps/files/lib/Controller/TransferOwnershipController.php +++ b/apps/files/lib/Controller/TransferOwnershipController.php @@ -82,6 +82,17 @@ class TransferOwnershipController extends OCSController { /** * @NoAdminRequired + * + * Transfer the ownership to another user + * + * @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{}> + * + * 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 @@ class TransferOwnershipController extends OCSController { /** * @NoAdminRequired + * + * Accept an ownership transfer + * + * @param int $id ID of the ownership transfer + * + * @return DataResponse<Http::STATUS_OK|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, 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 @@ class TransferOwnershipController extends OCSController { /** * @NoAdminRequired + * + * Reject an ownership transfer + * + * @param int $id ID of the ownership transfer + * + * @return DataResponse<Http::STATUS_OK|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, 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 43be43aa116..01f85a7c939 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\Files\Service\ViewConfig; 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\IUserSession; use OCP\Share\IManager; /** - * Class ViewController - * * @package OCA\Files\Controller */ +#[IgnoreOpenAPI] class ViewController extends Controller { private IURLGenerator $urlGenerator; private IL10N $l10n; |