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

files: Add OpenAPI spec

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

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 @@ public function __construct(IConfig $config) {
 
 	/**
 	 * 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\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<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 @@ 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<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 @@ public function __construct($appName, IRequest $request, $corsMethods, $corsAllo
 
 	/**
 	 * @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 @@ 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<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 @@ 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<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 @@ 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<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 @@
 
 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 */

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<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 @@ 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<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 @@
  */
 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,14 +51,28 @@ public function __construct($appName, IRequest $request, ITemplateManager $templ
 
 	/**
 	 * @NoAdminRequired
+	 *
+	 * List the available templates
+	 *
+	 * @return DataResponse<Http::STATUS_OK, array<FilesTemplateFileCreator>, array{}>
 	 */
 	public function list(): DataResponse {
 		return new DataResponse($this->templateManager->listTemplates());
 	}
 
 	/**
 	 * @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 @@ 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<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 @@ 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<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 @@ public function transfer(string $recipient, string $path): DataResponse {
 
 	/**
 	 * @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 @@ public function accept(int $id): DataResponse {
 
 	/**
 	 * @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\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;

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' => [