cloud_federation_api: Add OpenAPI spec

Signed-off-by: jld3103 <jld3103yt@gmail.com>

1 files changed, 35 insertions, 24 deletions

diff --git a/apps/cloud_federation_api/lib/Controller/RequestHandlerController.php b/apps/cloud_federation_api/lib/Controller/RequestHandlerController.php
index 5a06e14c3ca..416dca67160 100644
--- a/apps/cloud_federation_api/lib/Controller/RequestHandlerController.php
+++ b/apps/cloud_federation_api/lib/Controller/RequestHandlerController.php
@@ -5,6 +5,7 @@
  * @author Bjoern Schiessle <bjoern@schiessle.org>
  * @author Christoph Wurst <christoph@winzerhof-wurst.at>
  * @author Roeland Jago Douma <roeland@famdouma.nl>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @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 OCP\Share\Exceptions\ShareNotFound;
 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,26 +104,28 @@ class RequestHandlerController extends Controller {
 	}
 
 	/**
-	 * 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) {
 
@@ -229,19 +235,24 @@ class RequestHandlerController extends Controller {
 	}
 
 	/**
-	 * 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, CloudFederationApiValidationError, array{}>|JSONResponse<Http::STATUS_FORBIDDEN|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($notificationType, $resourceType, $providerId, ?array $notification) {
 
 		// check if all required parameters are set
 		if ($notificationType === null ||