Bringup OpenAPI

apps/cloud_federation_api/lib/Capabilities.php

@@ -3,6 +3,7 @@
  * @copyright Copyright (c) 2017 Bjoern Schiessle <[email protected]>
  *
  * @author Bjoern Schiessle <[email protected]>
+ * @author Kate Döen <[email protected]>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -36,6 +37,22 @@ public function __construct(IURLGenerator $urlGenerator) {
 
 	/**
 	 * Function an app uses to return the capabilities
+	 *
+	 * @return array{
+	 *     ocm: array{
+	 *         enabled: bool,
+	 *         apiVersion: string,
+	 *         endPoint: string,
+	 *         resourceTypes: array{
+	 *             name: string,
+	 *             shareTypes: string[],
+	 *             protocols: array{
+	 *                 webdav: string,
+	 *	           },
+	 *	       }[],
+	 *	   },
+	 * }
+	 * @since 8.2.0
 	 */
 	public function getCapabilities() {
 		$url = $this->urlGenerator->linkToRouteAbsolute('cloud_federation_api.requesthandlercontroller.addShare');

apps/cloud_federation_api/lib/Controller/RequestHandlerController.php

@@ -5,6 +5,7 @@
  * @author Bjoern Schiessle <[email protected]>
  * @author Christoph Wurst <[email protected]>
  * @author Roeland Jago Douma <[email protected]>
+ * @author Kate Döen <[email protected]>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -25,6 +26,7 @@
 namespace OCA\CloudFederationAPI\Controller;
 
 use OCA\CloudFederationAPI\Config;
+use OCA\CloudFederationAPI\ResponseDefinitions;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\JSONResponse;
@@ -44,11 +46,13 @@
 use Psr\Log\LoggerInterface;
 
 /**
- * Class RequestHandlerController
- *
- * handle API between different Cloud instances
+ * Open-Cloud-Mesh-API
  *
  * @package OCA\CloudFederationAPI\Controller
+ *
+ * @psalm-import-type CloudFederationApiAddShare from ResponseDefinitions
+ * @psalm-import-type CloudFederationApiValidationError from ResponseDefinitions
+ * @psalm-import-type CloudFederationApiError from ResponseDefinitions
  */
 class RequestHandlerController extends Controller {
 
@@ -100,44 +104,42 @@ public function __construct($appName,
 	}
 
 	/**
-	 * add share
+	 * Add share
 	 *
 	 * @NoCSRFRequired
 	 * @PublicPage
 	 * @BruteForceProtection(action=receiveFederatedShare)
 	 *
-	 * @param string $shareWith
-	 * @param string $name resource name (e.g. document.odt)
-	 * @param string $description share description (optional)
-	 * @param string $providerId resource UID on the provider side
-	 * @param string $owner provider specific UID of the user who owns the resource
-	 * @param string $ownerDisplayName display name of the user who shared the item
-	 * @param string $sharedBy provider specific UID of the user who shared the resource
-	 * @param string $sharedByDisplayName display name of the user who shared the resource
-	 * @param array $protocol (e,.g. ['name' => 'webdav', 'options' => ['username' => 'john', 'permissions' => 31]])
-	 * @param string $shareType ('group' or 'user' share)
-	 * @param $resourceType ('file', 'calendar',...)
-	 * @return Http\DataResponse|JSONResponse
+	 * @param string $shareWith The user who the share will be shared with
+	 * @param string $name The resource name (e.g. document.odt)
+	 * @param string|null $description Share description
+	 * @param string $providerId Resource UID on the provider side
+	 * @param string $owner Provider specific UID of the user who owns the resource
+	 * @param string|null $ownerDisplayName Display name of the user who shared the item
+	 * @param string|null $sharedBy Provider specific UID of the user who shared the resource
+	 * @param string|null $sharedByDisplayName Display name of the user who shared the resource
+	 * @param array{name: string[], options: array<string, mixed>} $protocol e,.g. ['name' => 'webdav', 'options' => ['username' => 'john', 'permissions' => 31]]
+	 * @param string $shareType 'group' or 'user' share
+	 * @param string $resourceType 'file', 'calendar',...
 	 *
-	 * Example: curl -H "Content-Type: application/json" -X POST -d '{"shareWith":"admin1@serve1","name":"welcome server2.txt","description":"desc","providerId":"2","owner":"admin2@http://localhost/server2","ownerDisplayName":"admin2 display","shareType":"user","resourceType":"file","protocol":{"name":"webdav","options":{"sharedSecret":"secret","permissions":"webdav-property"}}}' http://localhost/server/index.php/ocm/shares
+	 * @return JSONResponse<Http::STATUS_CREATED, CloudFederationApiAddShare, array{}>|JSONResponse<Http::STATUS_BAD_REQUEST, CloudFederationApiValidationError, array{}>|JSONResponse<Http::STATUS_NOT_IMPLEMENTED, CloudFederationApiError, array{}>
+	 * 201: The notification was successfully received. The display name of the recipient might be returned in the body
+	 * 400: Bad request due to invalid parameters, e.g. when `shareWith` is not found or required properties are missing
+	 * 501: Share type or the resource type is not supported
 	 */
-	public function addShare($shareWith, $name, $description, $providerId, $owner, $ownerDisplayName, $sharedBy, $sharedByDisplayName, $protocol, $shareType, $resourceType) {
+	public function addShare(string $shareWith, string $name, ?string $description, string $providerId, string $owner, ?string $ownerDisplayName, ?string $sharedBy, ?string $sharedByDisplayName, array $protocol, string $shareType, string $resourceType): JSONResponse {
 
 		// check if all required parameters are set
-		if ($shareWith === null ||
-			$name === null ||
-			$providerId === null ||
-			$owner === null ||
-			$resourceType === null ||
-			$shareType === null ||
-			!is_array($protocol) ||
-			!isset($protocol['name']) ||
+		if (!isset($protocol['name']) ||
 			!isset($protocol['options']) ||
 			!is_array($protocol['options']) ||
 			!isset($protocol['options']['sharedSecret'])
 		) {
 			return new JSONResponse(
-				['message' => 'Missing arguments'],
+				[
+					'message' => 'Missing arguments',
+					'validationErrors' => [],
+				],
 				Http::STATUS_BAD_REQUEST
 			);
 		}
@@ -158,7 +160,10 @@ public function addShare($shareWith, $name, $description, $providerId, $owner, $
 
 			if (!$this->userManager->userExists($shareWith)) {
 				$response = new JSONResponse(
-					['message' => 'User "' . $shareWith . '" does not exists at ' . $this->urlGenerator->getBaseUrl()],
+					[
+						'message' => 'User "' . $shareWith . '" does not exists at ' . $this->urlGenerator->getBaseUrl(),
+						'validationErrors' => [],
+					],
 					Http::STATUS_BAD_REQUEST
 				);
 				$response->throttle();
@@ -169,7 +174,10 @@ public function addShare($shareWith, $name, $description, $providerId, $owner, $
 		if ($shareType === 'group') {
 			if (!$this->groupManager->groupExists($shareWith)) {
 				$response = new JSONResponse(
-					['message' => 'Group "' . $shareWith . '" does not exists at ' . $this->urlGenerator->getBaseUrl()],
+					[
+						'message' => 'Group "' . $shareWith . '" does not exists at ' . $this->urlGenerator->getBaseUrl(),
+						'validationErrors' => [],
+					],
 					Http::STATUS_BAD_REQUEST
 				);
 				$response->throttle();
@@ -192,20 +200,18 @@ public function addShare($shareWith, $name, $description, $providerId, $owner, $
 			$share = $this->factory->getCloudFederationShare($shareWith, $name, $description, $providerId, $owner, $ownerDisplayName, $sharedBy, $sharedByDisplayName, '', $shareType, $resourceType);
 			$share->setProtocol($protocol);
 			$provider->shareReceived($share);
-		} catch (ProviderDoesNotExistsException $e) {
+		} catch (ProviderDoesNotExistsException|ProviderCouldNotAddShareException $e) {
 			return new JSONResponse(
 				['message' => $e->getMessage()],
 				Http::STATUS_NOT_IMPLEMENTED
 			);
-		} catch (ProviderCouldNotAddShareException $e) {
-			return new JSONResponse(
-				['message' => $e->getMessage()],
-				$e->getCode()
-			);
 		} catch (\Exception $e) {
 			$this->logger->error($e->getMessage(), ['exception' => $e]);
 			return new JSONResponse(
-				['message' => 'Internal error at ' . $this->urlGenerator->getBaseUrl()],
+				[
+					'message' => 'Internal error at ' . $this->urlGenerator->getBaseUrl(),
+					'validationErrors' => [],
+				],
 				Http::STATUS_BAD_REQUEST
 			);
 		}
@@ -222,28 +228,32 @@ public function addShare($shareWith, $name, $description, $providerId, $owner, $
 	}
 
 	/**
-	 * receive notification about existing share
+	 * Send a notification about an existing share
 	 *
 	 * @NoCSRFRequired
 	 * @PublicPage
 	 * @BruteForceProtection(action=receiveFederatedShareNotification)
 	 *
-	 * @param string $notificationType (notification type, e.g. SHARE_ACCEPTED)
-	 * @param string $resourceType (calendar, file, contact,...)
-	 * @param string $providerId id of the share
-	 * @param array $notification the actual payload of the notification
-	 * @return JSONResponse
+	 * @param string $notificationType Notification type, e.g. SHARE_ACCEPTED
+	 * @param string $resourceType calendar, file, contact,...
+	 * @param string|null $providerId ID of the share
+	 * @param array<string, mixed>|null $notification The actual payload of the notification
+	 *
+	 * @return JSONResponse<Http::STATUS_CREATED, array<string, mixed>, array{}>|JSONResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN, CloudFederationApiValidationError, array{}>|JSONResponse<Http::STATUS_NOT_IMPLEMENTED, CloudFederationApiError, array{}>
+	 * 201: The notification was successfully received
+	 * 400: Bad request due to invalid parameters, e.g. when `type` is invalid or missing
+	 * 403: Getting resource is not allowed
+	 * 501: The resource type is not supported
 	 */
-	public function receiveNotification($notificationType, $resourceType, $providerId, array $notification) {
+	public function receiveNotification(string $notificationType, string $resourceType, ?string $providerId, ?array $notification): JSONResponse {
 
 		// check if all required parameters are set
-		if ($notificationType === null ||
-			$resourceType === null ||
-			$providerId === null ||
-			!is_array($notification)
-		) {
+		if ($providerId === null || !is_array($notification)) {
 			return new JSONResponse(
-				['message' => 'Missing arguments'],
+				[
+					'message' => 'Missing arguments',
+					'validationErrors' => [],
+				],
 				Http::STATUS_BAD_REQUEST
 			);
 		}
@@ -253,12 +263,18 @@ public function receiveNotification($notificationType, $resourceType, $providerI
 			$result = $provider->notificationReceived($notificationType, $providerId, $notification);
 		} catch (ProviderDoesNotExistsException $e) {
 			return new JSONResponse(
-				['message' => $e->getMessage()],
+				[
+					'message' => $e->getMessage(),
+					'validationErrors' => [],
+				],
 				Http::STATUS_BAD_REQUEST
 			);
 		} catch (ShareNotFound $e) {
 			$response = new JSONResponse(
-				['message' => $e->getMessage()],
+				[
+					'message' => $e->getMessage(),
+					'validationErrors' => [],
+				],
 				Http::STATUS_BAD_REQUEST
 			);
 			$response->throttle();
@@ -271,12 +287,21 @@ public function receiveNotification($notificationType, $resourceType, $providerI
 		} catch (BadRequestException $e) {
 			return new JSONResponse($e->getReturnMessage(), Http::STATUS_BAD_REQUEST);
 		} catch (AuthenticationFailedException $e) {
-			$response = new JSONResponse(['message' => 'RESOURCE_NOT_FOUND'], Http::STATUS_FORBIDDEN);
+			$response = new JSONResponse(
+				[
+					'message' => 'RESOURCE_NOT_FOUND',
+					'validationErrors' => [],
+				],
+				Http::STATUS_FORBIDDEN
+			);
 			$response->throttle();
 			return $response;
 		} catch (\Exception $e) {
 			return new JSONResponse(
-				['message' => 'Internal error at ' . $this->urlGenerator->getBaseUrl()],
+				[
+					'message' => 'Internal error at ' . $this->urlGenerator->getBaseUrl(),
+					'validationErrors' => [],
+				],
 				Http::STATUS_BAD_REQUEST
 			);
 		}

apps/cloud_federation_api/lib/ResponseDefinitions.php

@@ -0,0 +1,45 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2023 Kate Döen <[email protected]>
+ *
+ * @author Kate Döen <[email protected]>
+ *
+ * @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\CloudFederationAPI;
+
+/**
+ * @psalm-type CloudFederationApiAddShare = array{
+ *     recipientDisplayName: string,
+ * }
+ *
+ * @psalm-type CloudFederationApiError = array{
+ *     message: string,
+ * }
+ *
+ * @psalm-type CloudFederationApiValidationError = CloudFederationApiError&array{
+ *     validationErrors: array{
+ *          name: string,
+ *          message: string|null,
+ *     }[],
+ * }
+ */
+class ResponseDefinitions {
+}

apps/cloud_federation_api/openapi.json

@@ -351,8 +351,8 @@
                         "content": {
                             "application/json": {
                                 "schema": {
-                                    "type": "array",
-                                    "items": {
+                                    "type": "object",
+                                    "additionalProperties": {
                                         "type": "object"
                                     }
                                 }
@@ -370,7 +370,7 @@
                         }
                     },
                     "403": {
-                        "description": "Getting resource not allowed",
+                        "description": "Getting resource is not allowed",
                         "content": {
                             "application/json": {
                                 "schema": {

apps/comments/lib/Capabilities.php

@@ -28,6 +28,9 @@
 use OCP\Capabilities\ICapability;
 
 class Capabilities implements ICapability {
+	/**
+	 * @return array{files: array{comments: bool}}
+	 */
 	public function getCapabilities(): array {
 		return [
 			'files' => [

apps/comments/lib/Controller/NotificationsController.php

@@ -27,7 +27,7 @@
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Http\NotFoundResponse;
 use OCP\AppFramework\Http\RedirectResponse;
-use OCP\AppFramework\Http\Response;
+use OCP\AppFramework\Http;
 use OCP\Comments\IComment;
 use OCP\Comments\ICommentsManager;
 use OCP\Files\IRootFolder;
@@ -73,8 +73,17 @@ public function __construct(
 	/**
 	 * @PublicPage
 	 * @NoCSRFRequired
+	 *
+	 * View a notification
+	 *
+	 * @param string $id ID of the notification
+	 *
+	 * @return RedirectResponse<Http::STATUS_SEE_OTHER, array{}>|NotFoundResponse<Http::STATUS_NOT_FOUND, array{}>
+	 *
+	 * 303: Redirected to notification
+	 * 404: Notification not found
 	 */
-	public function view(string $id): Response {
+	public function view(string $id): RedirectResponse|NotFoundResponse {
 		$currentUser = $this->userSession->getUser();
 		if (!$currentUser instanceof IUser) {
 			return new RedirectResponse(