1 files changed, 42 insertions, 35 deletions

diff --git a/apps/files_sharing/lib/Controller/ShareInfoController.php b/apps/files_sharing/lib/Controller/ShareInfoController.php
index b6242f9ee9a..b7e79aec830 100644
--- a/apps/files_sharing/lib/Controller/ShareInfoController.php
+++ b/apps/files_sharing/lib/Controller/ShareInfoController.php
@@ -1,31 +1,19 @@
 <?php
+
 /**
- * @copyright Copyright (c) 2016 Roeland Jago Douma <roeland@famdouma.nl>
- *
- * @author Morris Jobke <hey@morrisjobke.de>
- * @author Roeland Jago Douma <roeland@famdouma.nl>
- *
- * @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/>.
- *
+ * SPDX-FileCopyrightText: 2016 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 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\Attribute\BruteForceProtection;
+use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
+use OCP\AppFramework\Http\Attribute\OpenAPI;
+use OCP\AppFramework\Http\Attribute\PublicPage;
 use OCP\AppFramework\Http\JSONResponse;
 use OCP\Constants;
 use OCP\Files\File;
@@ -35,11 +23,11 @@ use OCP\IRequest;
 use OCP\Share\Exceptions\ShareNotFound;
 use OCP\Share\IManager;
 
+/**
+ * @psalm-import-type Files_SharingShareInfo from ResponseDefinitions
+ */
 class ShareInfoController extends ApiController {
 
-	/** @var IManager */
-	private $shareManager;
-
 	/**
 	 * ShareInfoController constructor.
 	 *
@@ -47,24 +35,31 @@ class ShareInfoController extends ApiController {
 	 * @param IRequest $request
 	 * @param IManager $shareManager
 	 */
-	public function __construct(string $appName,
-								IRequest $request,
-								IManager $shareManager) {
+	public function __construct(
+		string $appName,
+		IRequest $request,
+		private IManager $shareManager,
+	) {
 		parent::__construct($appName, $request);
-
-		$this->shareManager = $shareManager;
 	}
 
 	/**
-	 * @PublicPage
-	 * @NoCSRFRequired
-	 * @BruteForceProtection(action=shareinfo)
+	 * 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, Files_SharingShareInfo, array{}>|JSONResponse<Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, list<empty>, array{}>
 	 *
-	 * @param string $t
-	 * @param ?string $password
-	 * @param ?string $dir
-	 * @return JSONResponse
+	 * 200: Share info returned
+	 * 403: Getting share info is not allowed
+	 * 404: Share not found
 	 */
+	#[PublicPage]
+	#[NoCSRFRequired]
+	#[BruteForceProtection(action: 'shareinfo')]
+	#[OpenAPI(scope: OpenAPI::SCOPE_DEFAULT)]
 	public function info(string $t, ?string $password = null, ?string $dir = null, int $depth = -1): JSONResponse {
 		try {
 			$share = $this->shareManager->getShareByToken($t);
@@ -99,6 +94,9 @@ class ShareInfoController extends ApiController {
 		return new JSONResponse($this->parseNode($node, $permissionMask, $depth));
 	}
 
+	/**
+	 * @return Files_SharingShareInfo
+	 */
 	private function parseNode(Node $node, int $permissionMask, int $depth): array {
 		if ($node instanceof File) {
 			return $this->parseFile($node, $permissionMask);
@@ -107,10 +105,16 @@ class ShareInfoController extends ApiController {
 		return $this->parseFolder($node, $permissionMask, $depth);
 	}
 
+	/**
+	 * @return Files_SharingShareInfo
+	 */
 	private function parseFile(File $file, int $permissionMask): array {
 		return $this->format($file, $permissionMask);
 	}
 
+	/**
+	 * @return Files_SharingShareInfo
+	 */
 	private function parseFolder(Folder $folder, int $permissionMask, int $depth): array {
 		$data = $this->format($folder, $permissionMask);
 
@@ -128,6 +132,9 @@ class ShareInfoController extends ApiController {
 		return $data;
 	}
 
+	/**
+	 * @return Files_SharingShareInfo
+	 */
 	private function format(Node $node, int $permissionMask): array {
 		$entry = [];