Merge pull request #39327 from nextcloud/feature/openapi/files

files: Add OpenAPI spec

apps/files/composer/composer/autoload_classmap.php

@@ -61,6 +61,7 @@ return array(
     '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',

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',

apps/files/lib/Capabilities.php

@@ -38,12 +38,14 @@ class Capabilities implements ICapability {
 
 	/**
 	 * Return this classes capabilities
+	 *
+	 * @return array{files: array{bigfilechunking: bool, blacklisted_files: array<mixed>}}
 	 */
 	public function getCapabilities() {
 		return [
 			'files' => [
 				'bigfilechunking' => true,
-				'blacklisted_files' => $this->config->getSystemValue('blacklisted_files', ['.htaccess'])
+				'blacklisted_files' => (array)$this->config->getSystemValue('blacklisted_files', ['.htaccess'])
 			],
 		];
 	}

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');

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()) {

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 */

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);

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());

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 {

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;

apps/files/lib/DirectEditingCapabilities.php

@@ -38,6 +38,9 @@ class DirectEditingCapabilities implements ICapability, IInitialStateExcludedCap
 		$this->urlGenerator = $urlGenerator;
 	}
 
+	/**
+	 * @return array{files: array{directEditing: array{url: string, etag: string, supportsFileId: bool}}}
+	 */
 	public function getCapabilities() {
 		return [
 			'files' => [

apps/files/lib/ResponseDefinitions.php

@@ -0,0 +1,67 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2023 Kate Döen <kate.doeen@nextcloud.com>
+ *
+ * @author Kate Döen <kate.doeen@nextcloud.com>
+ *
+ * @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 <http://www.gnu.org/licenses/>.
+ *
+ */
+
+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 {
+}

lib/public/Files/Template/TemplateFileCreator.php

@@ -31,10 +31,13 @@ namespace OCP\Files\Template;
  */
 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 @@ final class TemplateFileCreator implements \JsonSerializable {
 
 	/**
 	 * @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 [