files_sharing: Add OpenAPI spec

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

8 files changed, 232 insertions, 132 deletions

diff --git a/apps/files_sharing/lib/Controller/AcceptController.php b/apps/files_sharing/lib/Controller/AcceptController.php
index c97780d6f0c..60bdaf519be 100644
--- a/apps/files_sharing/lib/Controller/AcceptController.php
+++ b/apps/files_sharing/lib/Controller/AcceptController.php
@@ -6,6 +6,7 @@ declare(strict_types=1);
  * @copyright Copyright (c) 2020, Roeland Jago Douma <roeland@famdouma.nl>
  *
  * @author Roeland Jago Douma <roeland@famdouma.nl>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -27,6 +28,7 @@ namespace OCA\Files_Sharing\Controller;
 
 use OCA\Files_Sharing\AppInfo\Application;
 use OCP\AppFramework\Controller;
+use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\NotFoundResponse;
 use OCP\AppFramework\Http\RedirectResponse;
 use OCP\AppFramework\Http\Response;
@@ -36,6 +38,7 @@ use OCP\IUserSession;
 use OCP\Share\Exceptions\ShareNotFound;
 use OCP\Share\IManager as ShareManager;
 
+#[IgnoreOpenAPI]
 class AcceptController extends Controller {
 
 	/** @var ShareManager */
diff --git a/apps/files_sharing/lib/Controller/DeletedShareAPIController.php b/apps/files_sharing/lib/Controller/DeletedShareAPIController.php
index 33bd9eeb4cd..ddd3816022e 100644
--- a/apps/files_sharing/lib/Controller/DeletedShareAPIController.php
+++ b/apps/files_sharing/lib/Controller/DeletedShareAPIController.php
@@ -11,6 +11,7 @@ declare(strict_types=1);
  * @author John Molakvoæ <skjnldsv@protonmail.com>
  * @author Julius Härtl <jus@bitgrid.net>
  * @author Roeland Jago Douma <roeland@famdouma.nl>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -30,7 +31,9 @@ declare(strict_types=1);
  */
 namespace OCA\Files_Sharing\Controller;
 
+use OCA\Files_Sharing\ResponseDefinitions;
 use OCP\App\IAppManager;
+use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCS\OCSException;
 use OCP\AppFramework\OCS\OCSNotFoundException;
@@ -47,6 +50,9 @@ use OCP\Share\Exceptions\ShareNotFound;
 use OCP\Share\IManager as ShareManager;
 use OCP\Share\IShare;
 
+/**
+ * @psalm-import-type FilesSharingDeletedShare from ResponseDefinitions
+ */
 class DeletedShareAPIController extends OCSController {
 
 	/** @var ShareManager */
@@ -92,6 +98,8 @@ class DeletedShareAPIController extends OCSController {
 
 	/**
 	 * @suppress PhanUndeclaredClassMethod
+	 *
+	 * @return FilesSharingDeletedShare
 	 */
 	private function formatShare(IShare $share): array {
 		$result = [
@@ -176,6 +184,10 @@ class DeletedShareAPIController extends OCSController {
 
 	/**
 	 * @NoAdminRequired
+	 *
+	 * Get a list of all deleted shares
+	 *
+	 * @return DataResponse<Http::STATUS_OK, FilesSharingDeletedShare[], array{}>
 	 */
 	public function index(): DataResponse {
 		$groupShares = $this->shareManager->getDeletedSharedWith($this->userId, IShare::TYPE_GROUP, null, -1, 0);
@@ -195,7 +207,14 @@ class DeletedShareAPIController extends OCSController {
 	/**
 	 * @NoAdminRequired
 	 *
+	 * Undelete a deleted share
+	 *
+	 * @param string $id ID of the share
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
 	 * @throws OCSException
+	 * @throws OCSNotFoundException Share not found
+	 *
+	 * 200: Share undeleted successfully
 	 */
 	public function undelete(string $id): DataResponse {
 		try {
diff --git a/apps/files_sharing/lib/Controller/PublicPreviewController.php b/apps/files_sharing/lib/Controller/PublicPreviewController.php
index ee11cf5f3f0..089610f711f 100644
--- a/apps/files_sharing/lib/Controller/PublicPreviewController.php
+++ b/apps/files_sharing/lib/Controller/PublicPreviewController.php
@@ -5,6 +5,7 @@
  * @author Julius Härtl <jus@bitgrid.net>
  * @author Morris Jobke <hey@morrisjobke.de>
  * @author Roeland Jago Douma <roeland@famdouma.nl>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -82,11 +83,19 @@ class PublicPreviewController extends PublicShareController {
 	 * @PublicPage
 	 * @NoCSRFRequired
 	 *
-	 * @param string $file
-	 * @param int $x
-	 * @param int $y
-	 * @param bool $a
-	 * @return DataResponse|FileDisplayResponse
+	 * Get a preview for a shared file
+	 *
+	 * @param string $token Token of the share
+	 * @param string $file File in the share
+	 * @param int $x Width of the preview
+	 * @param int $y Height of the preview
+	 * @param bool $a Whether to not crop the preview
+	 * @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: string}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 *
+	 * 200: Preview returned
+	 * 400: Getting preview is not possible
+	 * 403: Getting preview is not allowed
+	 * 404: Share or preview not found
 	 */
 	public function getPreview(
 		string $token,
@@ -138,8 +147,15 @@ class PublicPreviewController extends PublicShareController {
 	 * @NoCSRFRequired
 	 * @NoSameSiteCookieRequired
 	 *
-	 * @param $token
-	 * @return DataResponse|FileDisplayResponse
+	 * Get a direct link preview for a shared file
+	 *
+	 * @param string $token Token of the share
+	 * @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: string}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 *
+	 * 200: Preview returned
+	 * 400: Getting preview is not possible
+	 * 403: Getting preview is not allowed
+	 * 404: Share or preview not found
 	 */
 	public function directLink(string $token) {
 		// No token no image
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);
diff --git a/apps/files_sharing/lib/Controller/ShareAPIController.php b/apps/files_sharing/lib/Controller/ShareAPIController.php
index 5d5015cfca6..b2a2e774766 100644
--- a/apps/files_sharing/lib/Controller/ShareAPIController.php
+++ b/apps/files_sharing/lib/Controller/ShareAPIController.php
@@ -26,6 +26,7 @@ declare(strict_types=1);
  * @author Valdnet <47037905+Valdnet@users.noreply.github.com>
  * @author Vincent Petry <vincent@nextcloud.com>
  * @author waleczny <michal@walczak.xyz>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license AGPL-3.0
  *
@@ -42,6 +43,7 @@ declare(strict_types=1);
  * along with this program. If not, see <http://www.gnu.org/licenses/>
  *
  */
+
 namespace OCA\Files_Sharing\Controller;
 
 use Exception;
@@ -50,8 +52,10 @@ use OC\Files\Storage\Wrapper\Wrapper;
 use OCA\Files\Helper;
 use OCA\Files_Sharing\Exceptions\SharingRightsException;
 use OCA\Files_Sharing\External\Storage;
+use OCA\Files_Sharing\ResponseDefinitions;
 use OCA\Files_Sharing\SharedStorage;
 use OCP\App\IAppManager;
+use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCS\OCSBadRequestException;
 use OCP\AppFramework\OCS\OCSException;
@@ -85,9 +89,9 @@ use Psr\Container\ContainerExceptionInterface;
 use Psr\Log\LoggerInterface;
 
 /**
- * Class Share20OCS
- *
  * @package OCA\Files_Sharing\API
+ *
+ * @psalm-import-type FilesSharingShare from ResponseDefinitions
  */
 class ShareAPIController extends OCSController {
 
@@ -173,7 +177,7 @@ class ShareAPIController extends OCSController {
 	 *
 	 * @param \OCP\Share\IShare $share
 	 * @param Node|null $recipientNode
-	 * @return array
+	 * @return FilesSharingShare
 	 * @throws NotFoundException In case the node can't be resolved.
 	 *
 	 * @suppress PhanUndeclaredClassMethod
@@ -258,7 +262,6 @@ class ShareAPIController extends OCSController {
 			$result['share_with_displayname_unique'] = $sharedWith !== null ? (
 				 !empty($sharedWith->getSystemEMailAddress()) ? $sharedWith->getSystemEMailAddress() : $sharedWith->getUID()
 			) : $share->getSharedWith();
-			$result['status'] = [];
 
 			$userStatuses = $this->userStatusManager->getUserStatuses([$share->getSharedWith()]);
 			$userStatus = array_shift($userStatuses);
@@ -328,7 +331,9 @@ class ShareAPIController extends OCSController {
 			$result['share_with_displayname'] = '';
 
 			try {
-				$result = array_merge($result, $this->getRoomShareHelper()->formatShare($share));
+				/** @var array{share_with_displayname: string, share_with_link: string, share_with?: string, token?: string} $roomShare */
+				$roomShare = $this->getRoomShareHelper()->formatShare($share);
+				$result = array_merge($result, $roomShare);
 			} catch (QueryException $e) {
 			}
 		} elseif ($share->getShareType() === IShare::TYPE_DECK) {
@@ -336,7 +341,9 @@ class ShareAPIController extends OCSController {
 			$result['share_with_displayname'] = '';
 
 			try {
-				$result = array_merge($result, $this->getDeckShareHelper()->formatShare($share));
+				/** @var array{share_with: string, share_with_displayname: string, share_with_link: string} $deckShare */
+				$deckShare = $this->getDeckShareHelper()->formatShare($share);
+				$result = array_merge($result, $deckShare);
 			} catch (QueryException $e) {
 			}
 		} elseif ($share->getShareType() === IShare::TYPE_SCIENCEMESH) {
@@ -344,7 +351,9 @@ class ShareAPIController extends OCSController {
 			$result['share_with_displayname'] = '';
 
 			try {
-				$result = array_merge($result, $this->getSciencemeshShareHelper()->formatShare($share));
+				/** @var array{share_with: string, share_with_displayname: string, token: string} $scienceMeshShare */
+				$scienceMeshShare = $this->getSciencemeshShareHelper()->formatShare($share);
+				$result = array_merge($result, $scienceMeshShare);
 			} catch (QueryException $e) {
 			}
 		}
@@ -355,7 +364,7 @@ class ShareAPIController extends OCSController {
 
 		$result['attributes'] = null;
 		if ($attributes = $share->getAttributes()) {
-			$result['attributes'] =  \json_encode($attributes->toArray());
+			$result['attributes'] =  (string)\json_encode($attributes->toArray());
 		}
 
 		return $result;
@@ -493,14 +502,16 @@ class ShareAPIController extends OCSController {
 
 
 	/**
+	 * @NoAdminRequired
+	 *
 	 * Get a specific share by id
 	 *
-	 * @NoAdminRequired
+	 * @param string $id ID of the share
+	 * @param bool $include_tags Include tags in the share
+	 * @return DataResponse<Http::STATUS_OK, FilesSharingShare, array{}>
+	 * @throws OCSNotFoundException Share not found
 	 *
-	 * @param string $id
-	 * @param bool $includeTags
-	 * @return DataResponse
-	 * @throws OCSNotFoundException
+	 * 200: Share returned
 	 */
 	public function getShare(string $id, bool $include_tags = false): DataResponse {
 		try {
@@ -529,13 +540,16 @@ class ShareAPIController extends OCSController {
 	}
 
 	/**
+	 * @NoAdminRequired
+	 *
 	 * Delete a share
 	 *
-	 * @NoAdminRequired
+	 * @param string $id ID of the share
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @throws OCSNotFoundException Share not found
+	 * @throws OCSForbiddenException Missing permissions to delete the share
 	 *
-	 * @param string $id
-	 * @return DataResponse
-	 * @throws OCSNotFoundException
+	 * 200: Share deleted successfully
 	 */
 	public function deleteShare(string $id): DataResponse {
 		try {
@@ -574,25 +588,28 @@ class ShareAPIController extends OCSController {
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @param string $path
-	 * @param int $permissions
-	 * @param int $shareType
-	 * @param string $shareWith
-	 * @param string $publicUpload
-	 * @param string $password
-	 * @param string $sendPasswordByTalk
-	 * @param string $expireDate
-	 * @param string $label
-	 * @param string $attributes
+	 * Create a share
 	 *
-	 * @return DataResponse
-	 * @throws NotFoundException
-	 * @throws OCSBadRequestException
+	 * @param string|null $path Path of the share
+	 * @param int|null $permissions Permissions for the share
+	 * @param int $shareType Type of the share
+	 * @param string|null $shareWith The entity this should be shared with
+	 * @param string $publicUpload If public uploading is allowed
+	 * @param string $password Password for the share
+	 * @param string|null $sendPasswordByTalk Send the password for the share over Talk
+	 * @param string $expireDate Expiry date of the share
+	 * @param string $note Note for the share
+	 * @param string $label Label for the share (only used in link and email)
+	 * @param string|null $attributes Additional attributes for the share
+	 *
+	 * @return DataResponse<Http::STATUS_OK, FilesSharingShare, array{}>
+	 * @throws OCSBadRequestException Unknown share type
 	 * @throws OCSException
-	 * @throws OCSForbiddenException
-	 * @throws OCSNotFoundException
-	 * @throws InvalidPathException
+	 * @throws OCSForbiddenException Creating the share is not allowed
+	 * @throws OCSNotFoundException Creating the share failed
 	 * @suppress PhanUndeclaredClassMethod
+	 *
+	 * 200: Share created
 	 */
 	public function createShare(
 		string $path = null,
@@ -862,7 +879,7 @@ class ShareAPIController extends OCSController {
 	 * @param null|Node $node
 	 * @param boolean $includeTags
 	 *
-	 * @return array
+	 * @return FilesSharingShare[]
 	 */
 	private function getSharedWithMe($node, bool $includeTags): array {
 		$userShares = $this->shareManager->getSharedWith($this->currentUser, IShare::TYPE_USER, $node, -1, 0);
@@ -899,7 +916,7 @@ class ShareAPIController extends OCSController {
 	/**
 	 * @param \OCP\Files\Node $folder
 	 *
-	 * @return array
+	 * @return FilesSharingShare[]
 	 * @throws OCSBadRequestException
 	 * @throws NotFoundException
 	 */
@@ -951,27 +968,20 @@ class ShareAPIController extends OCSController {
 	}
 
 	/**
-	 * The getShares function.
-	 *
 	 * @NoAdminRequired
 	 *
-	 * @param string $shared_with_me
-	 * @param string $reshares
-	 * @param string $subfiles
-	 * @param string $path
+	 * Get shares of the current user
 	 *
-	 * - Get shares by the current user
-	 * - Get shares by the current user and reshares (?reshares=true)
-	 * - Get shares with the current user (?shared_with_me=true)
-	 * - Get shares for a specific path (?path=...)
-	 * - Get all shares in a folder (?subfiles=true&path=..)
+	 * @param string $shared_with_me Only get shares with the current user
+	 * @param string $reshares Only get shares by the current user and reshares
+	 * @param string $subfiles Only get all shares in a folder
+	 * @param string $path Get shares for a specific path
+	 * @param string $include_tags Include tags in the share
 	 *
-	 * @param string $include_tags
+	 * @return DataResponse<Http::STATUS_OK, FilesSharingShare[], array{}>
+	 * @throws OCSNotFoundException The folder was not found or is inaccessible
 	 *
-	 * @return DataResponse
-	 * @throws NotFoundException
-	 * @throws OCSBadRequestException
-	 * @throws OCSNotFoundException
+	 * 200: Shares returned
 	 */
 	public function getShares(
 		string $shared_with_me = 'false',
@@ -1016,7 +1026,7 @@ class ShareAPIController extends OCSController {
 	 * @param bool $subFiles
 	 * @param bool $includeTags
 	 *
-	 * @return array
+	 * @return FilesSharingShare[]
 	 * @throws NotFoundException
 	 * @throws OCSBadRequestException
 	 */
@@ -1095,25 +1105,19 @@ class ShareAPIController extends OCSController {
 
 
 	/**
-	 * The getInheritedShares function.
-	 * returns all shares relative to a file, including parent folders shares rights.
-	 *
 	 * @NoAdminRequired
 	 *
-	 * @param string $path
+	 * Get all shares relative to a file, including parent folders shares rights
 	 *
-	 * - Get shares by the current user
-	 * - Get shares by the current user and reshares (?reshares=true)
-	 * - Get shares with the current user (?shared_with_me=true)
-	 * - Get shares for a specific path (?path=...)
-	 * - Get all shares in a folder (?subfiles=true&path=..)
+	 * @param string $path Path all shares will be relative to
 	 *
-	 * @return DataResponse
+	 * @return DataResponse<Http::STATUS_OK, FilesSharingShare[], array{}>
 	 * @throws InvalidPathException
 	 * @throws NotFoundException
-	 * @throws OCSNotFoundException
-	 * @throws OCSBadRequestException
+	 * @throws OCSNotFoundException The given path is invalid
 	 * @throws SharingRightsException
+	 *
+	 * 200: Shares returned
 	 */
 	public function getInheritedShares(string $path): DataResponse {
 
@@ -1197,22 +1201,24 @@ class ShareAPIController extends OCSController {
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @param string $id
-	 * @param int $permissions
-	 * @param string $password
-	 * @param string $sendPasswordByTalk
-	 * @param string $publicUpload
-	 * @param string $expireDate
-	 * @param string $note
-	 * @param string $label
-	 * @param string $hideDownload
-	 * @param string $attributes
-	 * @return DataResponse
-	 * @throws LockedException
-	 * @throws NotFoundException
-	 * @throws OCSBadRequestException
-	 * @throws OCSForbiddenException
-	 * @throws OCSNotFoundException
+	 * Update a share
+	 *
+	 * @param string $id ID of the share
+	 * @param int|null $permissions New permissions
+	 * @param string|null $password New password
+	 * @param string|null $sendPasswordByTalk New condition if the password should be send over Talk
+	 * @param string|null $publicUpload New condition if public uploading is allowed
+	 * @param string|null $expireDate New expiry date
+	 * @param string|null $note New note
+	 * @param string|null $label New label
+	 * @param string|null $hideDownload New condition if the download should be hidden
+	 * @param string|null $attributes New additional attributes
+	 * @return DataResponse<Http::STATUS_OK, FilesSharingShare, array{}>
+	 * @throws OCSBadRequestException Share could not be updated because the requested changes are invalid
+	 * @throws OCSForbiddenException Missing permissions to update the share
+	 * @throws OCSNotFoundException Share not found
+	 *
+	 * 200: Share updated successfully
 	 */
 	public function updateShare(
 		string $id,
@@ -1400,6 +1406,10 @@ class ShareAPIController extends OCSController {
 
 	/**
 	 * @NoAdminRequired
+	 *
+	 * Get all shares that are still pending
+	 *
+	 * @return DataResponse<Http::STATUS_OK, FilesSharingShare[], array{}>
 	 */
 	public function pendingShares(): DataResponse {
 		$pendingShares = [];
@@ -1434,7 +1444,6 @@ class ShareAPIController extends OCSController {
 
 			try {
 				$formattedShare = $this->formatShare($share, $node);
-				$formattedShare['status'] = $share->getStatus();
 				$formattedShare['path'] = '/' . $share->getNode()->getName();
 				$formattedShare['permissions'] = 0;
 				return $formattedShare;
@@ -1451,11 +1460,15 @@ class ShareAPIController extends OCSController {
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @param string $id
-	 * @return DataResponse
-	 * @throws OCSNotFoundException
+	 * Accept a share
+	 *
+	 * @param string $id ID of the share
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
+	 * @throws OCSNotFoundException Share not found
 	 * @throws OCSException
-	 * @throws OCSBadRequestException
+	 * @throws OCSBadRequestException Share could not be accepted
+	 *
+	 * 200: Share accepted successfully
 	 */
 	public function acceptShare(string $id): DataResponse {
 		try {
diff --git a/apps/files_sharing/lib/Controller/ShareController.php b/apps/files_sharing/lib/Controller/ShareController.php
index f61665fe067..dc60463dac7 100644
--- a/apps/files_sharing/lib/Controller/ShareController.php
+++ b/apps/files_sharing/lib/Controller/ShareController.php
@@ -24,6 +24,7 @@
  * @author Sascha Sambale <mastixmc@gmail.com>
  * @author Thomas Müller <thomas.mueller@tmit.eu>
  * @author Vincent Petry <vincent@nextcloud.com>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license AGPL-3.0
  *
@@ -51,6 +52,7 @@ use OCA\Files_Sharing\Event\BeforeTemplateRenderedEvent;
 use OCA\Files_Sharing\Event\ShareLinkAccessedEvent;
 use OCP\Accounts\IAccountManager;
 use OCP\AppFramework\AuthPublicShareController;
+use OCP\AppFramework\Http\Attribute\IgnoreOpenAPI;
 use OCP\AppFramework\Http\NotFoundResponse;
 use OCP\AppFramework\Http\TemplateResponse;
 use OCP\Defaults;
@@ -74,10 +76,9 @@ use OCP\Share\IPublicShareTemplateFactory;
 use OCP\Template;
 
 /**
- * Class ShareController
- *
  * @package OCA\Files_Sharing\Controllers
  */
+#[IgnoreOpenAPI]
 class ShareController extends AuthPublicShareController {
 	protected ?Share\IShare $share = null;
 
diff --git a/apps/files_sharing/lib/Controller/ShareInfoController.php b/apps/files_sharing/lib/Controller/ShareInfoController.php
index b6242f9ee9a..14f69b9703f 100644
--- a/apps/files_sharing/lib/Controller/ShareInfoController.php
+++ b/apps/files_sharing/lib/Controller/ShareInfoController.php
@@ -4,6 +4,7 @@
  *
  * @author Morris Jobke <hey@morrisjobke.de>
  * @author Roeland Jago Douma <roeland@famdouma.nl>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -24,6 +25,7 @@
 namespace OCA\Files_Sharing\Controller;
 
 use OCA\Files_External\NotFoundException;
+use OCA\Files_Sharing\ResponseDefinitions;
 use OCP\AppFramework\ApiController;
 use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\JSONResponse;
@@ -35,6 +37,9 @@ use OCP\IRequest;
 use OCP\Share\Exceptions\ShareNotFound;
 use OCP\Share\IManager;
 
+/**
+ * @psalm-import-type FilesSharingShareInfo from ResponseDefinitions
+ */
 class ShareInfoController extends ApiController {
 
 	/** @var IManager */
@@ -60,10 +65,17 @@ class ShareInfoController extends ApiController {
 	 * @NoCSRFRequired
 	 * @BruteForceProtection(action=shareinfo)
 	 *
-	 * @param string $t
-	 * @param ?string $password
-	 * @param ?string $dir
-	 * @return JSONResponse
+	 * Get the info about a share
+	 *
+	 * @param string $t Token of the share
+	 * @param string|null $password Password of the share
+	 * @param string|null $dir Subdirectory to get info about
+	 * @param int $depth Maximum depth to get info about
+	 * @return JSONResponse<Http::STATUS_OK, FilesSharingShareInfo, array{}>|JSONResponse<Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, array{}>
+	 *
+	 * 200: Share info returned
+	 * 403: Getting share info is not allowed
+	 * 404: Share not found
 	 */
 	public function info(string $t, ?string $password = null, ?string $dir = null, int $depth = -1): JSONResponse {
 		try {
@@ -99,6 +111,9 @@ class ShareInfoController extends ApiController {
 		return new JSONResponse($this->parseNode($node, $permissionMask, $depth));
 	}
 
+	/**
+	 * @return FilesSharingShareInfo
+	 */
 	private function parseNode(Node $node, int $permissionMask, int $depth): array {
 		if ($node instanceof File) {
 			return $this->parseFile($node, $permissionMask);
@@ -107,10 +122,16 @@ class ShareInfoController extends ApiController {
 		return $this->parseFolder($node, $permissionMask, $depth);
 	}
 
+	/**
+	 * @return FilesSharingShareInfo
+	 */
 	private function parseFile(File $file, int $permissionMask): array {
 		return $this->format($file, $permissionMask);
 	}
 
+	/**
+	 * @return FilesSharingShareInfo
+	 */
 	private function parseFolder(Folder $folder, int $permissionMask, int $depth): array {
 		$data = $this->format($folder, $permissionMask);
 
@@ -128,6 +149,9 @@ class ShareInfoController extends ApiController {
 		return $data;
 	}
 
+	/**
+	 * @return FilesSharingShareInfo
+	 */
 	private function format(Node $node, int $permissionMask): array {
 		$entry = [];
 
diff --git a/apps/files_sharing/lib/Controller/ShareesAPIController.php b/apps/files_sharing/lib/Controller/ShareesAPIController.php
index 8daa7dc5ab9..a9288be9386 100644
--- a/apps/files_sharing/lib/Controller/ShareesAPIController.php
+++ b/apps/files_sharing/lib/Controller/ShareesAPIController.php
@@ -43,6 +43,8 @@ use function array_slice;
 use function array_values;
 use Generator;
 use OC\Collaboration\Collaborators\SearchResult;
+use OCA\Files_Sharing\ResponseDefinitions;
+use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCS\OCSBadRequestException;
 use OCP\AppFramework\OCSController;
@@ -56,6 +58,10 @@ use OCP\Share\IShare;
 use OCP\Share\IManager;
 use function usort;
 
+/**
+ * @psalm-import-type FilesSharingShareesSearchResult from ResponseDefinitions
+ * @psalm-import-type FilesSharingShareesRecommendedResult from ResponseDefinitions
+ */
 class ShareesAPIController extends OCSController {
 
 	/** @var string */
@@ -76,7 +82,7 @@ class ShareesAPIController extends OCSController {
 	/** @var int */
 	protected $limit = 10;
 
-	/** @var array */
+	/** @var FilesSharingShareesSearchResult */
 	protected $result = [
 		'exact' => [
 			'users' => [],
@@ -131,14 +137,18 @@ class ShareesAPIController extends OCSController {
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @param string $search
-	 * @param string $itemType
-	 * @param int $page
-	 * @param int $perPage
-	 * @param int|int[] $shareType
-	 * @param bool $lookup
-	 * @return DataResponse
-	 * @throws OCSBadRequestException
+	 * Search for sharees
+	 *
+	 * @param string $search Text to search for
+	 * @param string|null $itemType Limit to specific item types
+	 * @param int $page Page offset for searching
+	 * @param int $perPage Limit amount of search results per page
+	 * @param int|int[]|null $shareType Limit to specific share types
+	 * @param bool $lookup If a global lookup should be performed too
+	 * @return DataResponse<Http::STATUS_OK, FilesSharingShareesSearchResult, array{Link?: string}>
+	 * @throws OCSBadRequestException Invalid search parameters
+	 *
+	 * 200: Sharees search result returned
 	 */
 	public function search(string $search = '', string $itemType = null, int $page = 1, int $perPage = 200, $shareType = null, bool $lookup = false): DataResponse {
 
@@ -234,12 +244,12 @@ class ShareesAPIController extends OCSController {
 		$response = new DataResponse($this->result);
 
 		if ($hasMoreResults) {
-			$response->addHeader('Link', $this->getPaginationLink($page, [
+			$response->setHeaders(['Link' => $this->getPaginationLink($page, [
 				'search' => $search,
 				'itemType' => $itemType,
 				'shareType' => $shareTypes,
 				'perPage' => $perPage,
-			]));
+			])]);
 		}
 
 		return $response;
@@ -333,18 +343,18 @@ class ShareesAPIController extends OCSController {
 	/**
 	 * @NoAdminRequired
 	 *
-	 * @param string $itemType
-	 * @return DataResponse
-	 * @throws OCSBadRequestException
+	 * Find recommended sharees
+	 *
+	 * @param string $itemType Limit to specific item types
+	 * @param int|int[]|null $shareType Limit to specific share types
+	 * @return DataResponse<Http::STATUS_OK, FilesSharingShareesRecommendedResult, array{}>
 	 */
-	public function findRecommended(string $itemType = null, $shareType = null): DataResponse {
+	public function findRecommended(string $itemType, $shareType = null): DataResponse {
 		$shareTypes = [
 			IShare::TYPE_USER,
 		];
 
-		if ($itemType === null) {
-			throw new OCSBadRequestException('Missing itemType');
-		} elseif ($itemType === 'file' || $itemType === 'folder') {
+		if ($itemType === 'file' || $itemType === 'folder') {
 			if ($this->shareManager->allowGroupSharing()) {
 				$shareTypes[] = IShare::TYPE_GROUP;
 			}