files_sharing: Add OpenAPI spec

Signed-off-by: jld3103 <[email protected]>
nextcloud · Jul 12, 2023 · 3b18997 · 3b18997
1 parent 46284f1
commit 3b18997
Show file tree

Hide file tree

Showing 13 changed files with 961 additions and 235 deletions.
diff --git a/apps/files_sharing/composer/composer/autoload_classmap.php b/apps/files_sharing/composer/composer/autoload_classmap.php
@@ -76,6 +76,7 @@
     'OCA\\Files_Sharing\\Notification\\Listener' => $baseDir . '/../lib/Notification/Listener.php',
     'OCA\\Files_Sharing\\Notification\\Notifier' => $baseDir . '/../lib/Notification/Notifier.php',
     'OCA\\Files_Sharing\\OrphanHelper' => $baseDir . '/../lib/OrphanHelper.php',
+    'OCA\\Files_Sharing\\ResponseDefinitions' => $baseDir . '/../lib/ResponseDefinitions.php',
     'OCA\\Files_Sharing\\Scanner' => $baseDir . '/../lib/Scanner.php',
     'OCA\\Files_Sharing\\Settings\\Personal' => $baseDir . '/../lib/Settings/Personal.php',
     'OCA\\Files_Sharing\\ShareBackend\\File' => $baseDir . '/../lib/ShareBackend/File.php',

diff --git a/apps/files_sharing/composer/composer/autoload_static.php b/apps/files_sharing/composer/composer/autoload_static.php
@@ -91,6 +91,7 @@ class ComposerStaticInitFiles_Sharing
         'OCA\\Files_Sharing\\Notification\\Listener' => __DIR__ . '/..' . '/../lib/Notification/Listener.php',
         'OCA\\Files_Sharing\\Notification\\Notifier' => __DIR__ . '/..' . '/../lib/Notification/Notifier.php',
         'OCA\\Files_Sharing\\OrphanHelper' => __DIR__ . '/..' . '/../lib/OrphanHelper.php',
+        'OCA\\Files_Sharing\\ResponseDefinitions' => __DIR__ . '/..' . '/../lib/ResponseDefinitions.php',
         'OCA\\Files_Sharing\\Scanner' => __DIR__ . '/..' . '/../lib/Scanner.php',
         'OCA\\Files_Sharing\\Settings\\Personal' => __DIR__ . '/..' . '/../lib/Settings/Personal.php',
         'OCA\\Files_Sharing\\ShareBackend\\File' => __DIR__ . '/..' . '/../lib/ShareBackend/File.php',

diff --git a/apps/files_sharing/lib/Capabilities.php b/apps/files_sharing/lib/Capabilities.php
@@ -8,6 +8,7 @@
  * @author Roeland Jago Douma <[email protected]>
  * @author Tobias Kaminsky <[email protected]>
  * @author Vincent Petry <[email protected]>
+ * @author Kate Döen <[email protected]>
  *
  * @license AGPL-3.0
  *
@@ -50,6 +51,67 @@ public function __construct(IConfig $config, IManager $shareManager) {
 
 	/**
 	 * Return this classes capabilities
+	 *
+	 * @return array{
+	 *     files_sharing: array{
+	 *         api_enabled: bool,
+	 *         public: array{
+	 *             enabled: bool,
+	 *             password?: array{
+	 *                 enforced: bool,
+	 *                 askForOptionalPassword: bool
+	 *             },
+	 *     		   multiple_links?: bool,
+	 *             expire_date?: array{
+	 *                 enabled: bool,
+	 *                 days?: int,
+	 *                 enforced?: bool,
+	 *             },
+	 *             expire_date_internal?: array{
+	 *                 enabled: bool,
+	 *                 days?: int,
+	 *                 enforced?: bool,
+	 *             },
+	 *             expire_date_remote?: array{
+	 *                 enabled: bool,
+	 *                 days?: int,
+	 *                 enforced?: bool,
+	 *             },
+	 *             send_mail?: bool,
+	 *             upload?: bool,
+	 *             upload_files_drop?: bool,
+	 *         },
+	 *         user: array{
+	 *             send_mail: bool,
+	 *             expire_date?: array{
+	 *                 enabled: bool,
+	 *             },
+	 *         },
+	 *         resharing: bool,
+	 *         group_sharing?: bool,
+	 *         group?: array{
+	 *             enabled: bool,
+	 *             expire_date?: array{
+	 *                 enabled: bool,
+	 *             },
+	 *         },
+	 *         default_permissions?: int,
+	 *         federation: array{
+	 *             outgoing: bool,
+	 *             incoming: bool,
+	 *             expire_date: array{
+	 *                 enabled: bool,
+	 *             },
+	 *             expire_date_supported: array{
+	 *                 enabled: bool,
+	 *             },
+	 *         },
+	 *         sharee: array{
+	 *             query_lookup_default: bool,
+	 *             always_show_unique: bool,
+	 *         },
+	 *	   },
+	 * }
 	 */
 	public function getCapabilities() {
 		$res = [];

diff --git a/apps/files_sharing/lib/Controller/AcceptController.php b/apps/files_sharing/lib/Controller/AcceptController.php
@@ -6,6 +6,7 @@
  * @copyright Copyright (c) 2020, Roeland Jago Douma <[email protected]>
  *
  * @author Roeland Jago Douma <[email protected]>
+ * @author Kate Döen <[email protected]>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -27,6 +28,7 @@
 
 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\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
@@ -11,6 +11,7 @@
  * @author John Molakvoæ <[email protected]>
  * @author Julius Härtl <[email protected]>
  * @author Roeland Jago Douma <[email protected]>
+ * @author Kate Döen <[email protected]>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -30,7 +31,9 @@
  */
 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\IManager as ShareManager;
 use OCP\Share\IShare;
 
+/**
+ * @psalm-import-type FilesSharingDeletedShare from ResponseDefinitions
+ */
 class DeletedShareAPIController extends OCSController {
 
 	/** @var ShareManager */
@@ -92,6 +98,8 @@ public function __construct(string $appName,
 
 	/**
 	 * @suppress PhanUndeclaredClassMethod
+	 *
+	 * @return FilesSharingDeletedShare
 	 */
 	private function formatShare(IShare $share): array {
 		$result = [
@@ -176,6 +184,10 @@ private function formatShare(IShare $share): array {
 
 	/**
 	 * @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 @@ public function index(): DataResponse {
 	/**
 	 * @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
@@ -5,6 +5,7 @@
  * @author Julius Härtl <[email protected]>
  * @author Morris Jobke <[email protected]>
  * @author Roeland Jago Douma <[email protected]>
+ * @author Kate Döen <[email protected]>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -82,11 +83,19 @@ protected function isPasswordProtected(): bool {
 	 * @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 @@ public function getPreview(
 	 * @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
@@ -5,6 +5,7 @@
  * @author Bjoern Schiessle <[email protected]>
  * @author Joas Schilling <[email protected]>
  * @author Roeland Jago Douma <[email protected]>
+ * @author Kate Döen <[email protected]>
  *
  * @license AGPL-3.0
  *
@@ -24,13 +25,18 @@
 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;
 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 @@ public function __construct(
 	 *
 	 * 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 @@ public function getOpenShares() {
 	 *
 	 * 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 @@ public function acceptShare($id) {
 	 *
 	 * 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 @@ private static function extendShareInfo($share) {
 	/**
 	 * @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 @@ public function getShares() {
 	 *
 	 * 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 @@ public function getShare($id) {
 	 *
 	 * 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);