From c6806684d2deee11b64fb8250064115cea291659 Mon Sep 17 00:00:00 2001
From: jld3103 <jld3103yt@gmail.com>
Date: Wed, 15 Feb 2023 19:22:09 +0100
Subject: files_sharing: Add OpenAPI spec

Signed-off-by: jld3103 <jld3103yt@gmail.com>
---
 .../lib/Controller/RemoteController.php            | 46 ++++++++++++++--------
 1 file changed, 30 insertions(+), 16 deletions(-)

(limited to 'apps/files_sharing/lib/Controller/RemoteController.php')

diff --git a/apps/files_sharing/lib/Controller/RemoteController.php b/apps/files_sharing/lib/Controller/RemoteController.php
index 7618834e059..70cb55cae15 100644
--- a/apps/files_sharing/lib/Controller/RemoteController.php
+++ b/apps/files_sharing/lib/Controller/RemoteController.php
@@ -5,6 +5,7 @@
  * @author Bjoern Schiessle <bjoern@schiessle.org>
  * @author Joas Schilling <coding@schilljs.com>
  * @author Roeland Jago Douma <roeland@famdouma.nl>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license AGPL-3.0
  *
@@ -24,6 +25,8 @@
 namespace OCA\Files_Sharing\Controller;
 
 use OCA\Files_Sharing\External\Manager;
+use OCA\Files_Sharing\ResponseDefinitions;
+use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCS\OCSForbiddenException;
 use OCP\AppFramework\OCS\OCSNotFoundException;
@@ -31,6 +34,9 @@ use OCP\AppFramework\OCSController;
 use OCP\IRequest;
 use Psr\Log\LoggerInterface;
 
+/**
+ * @psalm-import-type FilesSharingRemoteShare from ResponseDefinitions
+ */
 class RemoteController extends OCSController {
 	/**
 	 * @NoAdminRequired
@@ -55,7 +61,7 @@ class RemoteController extends OCSController {
 	 *
 	 * Get list of pending remote shares
 	 *
-	 * @return DataResponse
+	 * @return DataResponse<Http::STATUS_OK, FilesSharingRemoteShare[], array{}>
 	 */
 	public function getOpenShares() {
 		return new DataResponse($this->externalManager->getOpenShares());
@@ -66,9 +72,11 @@ class RemoteController extends OCSController {
 	 *
 	 * Accept a remote share
 	 *
-	 * @param int $id
-	 * @return DataResponse
-	 * @throws OCSNotFoundException
+	 * @param int $id ID of the share
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @throws OCSNotFoundException Share not found
+	 *
+	 * 200: Share accepted successfully
 	 */
 	public function acceptShare($id) {
 		if ($this->externalManager->acceptShare($id)) {
@@ -86,9 +94,11 @@ class RemoteController extends OCSController {
 	 *
 	 * Decline a remote share
 	 *
-	 * @param int $id
-	 * @return DataResponse
-	 * @throws OCSNotFoundException
+	 * @param int $id ID of the share
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @throws OCSNotFoundException Share not found
+	 *
+	 * 200: Share declined successfully
 	 */
 	public function declineShare($id) {
 		if ($this->externalManager->declineShare($id)) {
@@ -125,9 +135,9 @@ class RemoteController extends OCSController {
 	/**
 	 * @NoAdminRequired
 	 *
-	 * List accepted remote shares
+	 * Get a list of accepted remote shares
 	 *
-	 * @return DataResponse
+	 * @return DataResponse<Http::STATUS_OK, FilesSharingRemoteShare[], array{}>
 	 */
 	public function getShares() {
 		$shares = $this->externalManager->getAcceptedShares();
@@ -141,9 +151,11 @@ class RemoteController extends OCSController {
 	 *
 	 * Get info of a remote share
 	 *
-	 * @param int $id
-	 * @return DataResponse
-	 * @throws OCSNotFoundException
+	 * @param int $id ID of the share
+	 * @return DataResponse<Http::STATUS_OK, FilesSharingRemoteShare, array{}>
+	 * @throws OCSNotFoundException Share not found
+	 *
+	 * 200: Share returned
 	 */
 	public function getShare($id) {
 		$shareInfo = $this->externalManager->getShare($id);
@@ -161,10 +173,12 @@ class RemoteController extends OCSController {
 	 *
 	 * Unshare a remote share
 	 *
-	 * @param int $id
-	 * @return DataResponse
-	 * @throws OCSNotFoundException
-	 * @throws OCSForbiddenException
+	 * @param int $id ID of the share
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @throws OCSNotFoundException Share not found
+	 * @throws OCSForbiddenException Unsharing is not possible
+	 *
+	 * 200: Share unshared successfully
 	 */
 	public function unshare($id) {
 		$shareInfo = $this->externalManager->getShare($id);
-- 
cgit v1.2.3