user_status: Add OpenAPI spec

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

apps/user_status/composer/composer/autoload_classmap.php

@@ -31,6 +31,7 @@ return array(
     'OCA\\UserStatus\\Migration\\Version0002Date20200902144824' => $baseDir . '/../lib/Migration/Version0002Date20200902144824.php',
     'OCA\\UserStatus\\Migration\\Version1000Date20201111130204' => $baseDir . '/../lib/Migration/Version1000Date20201111130204.php',
     'OCA\\UserStatus\\Migration\\Version2301Date20210809144824' => $baseDir . '/../lib/Migration/Version2301Date20210809144824.php',
+    'OCA\\UserStatus\\ResponseDefinitions' => $baseDir . '/../lib/ResponseDefinitions.php',
     'OCA\\UserStatus\\Service\\JSDataService' => $baseDir . '/../lib/Service/JSDataService.php',
     'OCA\\UserStatus\\Service\\PredefinedStatusService' => $baseDir . '/../lib/Service/PredefinedStatusService.php',
     'OCA\\UserStatus\\Service\\StatusService' => $baseDir . '/../lib/Service/StatusService.php',

apps/user_status/composer/composer/autoload_static.php

@@ -46,6 +46,7 @@ class ComposerStaticInitUserStatus
         'OCA\\UserStatus\\Migration\\Version0002Date20200902144824' => __DIR__ . '/..' . '/../lib/Migration/Version0002Date20200902144824.php',
         'OCA\\UserStatus\\Migration\\Version1000Date20201111130204' => __DIR__ . '/..' . '/../lib/Migration/Version1000Date20201111130204.php',
         'OCA\\UserStatus\\Migration\\Version2301Date20210809144824' => __DIR__ . '/..' . '/../lib/Migration/Version2301Date20210809144824.php',
+        'OCA\\UserStatus\\ResponseDefinitions' => __DIR__ . '/..' . '/../lib/ResponseDefinitions.php',
         'OCA\\UserStatus\\Service\\JSDataService' => __DIR__ . '/..' . '/../lib/Service/JSDataService.php',
         'OCA\\UserStatus\\Service\\PredefinedStatusService' => __DIR__ . '/..' . '/../lib/Service/PredefinedStatusService.php',
         'OCA\\UserStatus\\Service\\StatusService' => __DIR__ . '/..' . '/../lib/Service/StatusService.php',

apps/user_status/lib/Capabilities.php

@@ -6,6 +6,7 @@ declare(strict_types=1);
  * @copyright Copyright (c) 2020, Georg Ehrke
  *
  * @author Georg Ehrke <oc.list@georgehrke.com>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -40,6 +41,9 @@ class Capabilities implements ICapability {
 		$this->emojiHelper = $emojiHelper;
 	}
 
+	/**
+	 * @return array{user_status: array{enabled: bool, restore: bool, supports_emoji: bool}}
+	 */
 	public function getCapabilities() {
 		return [
 			'user_status' => [

apps/user_status/lib/Controller/HeartbeatController.php

@@ -6,6 +6,7 @@ declare(strict_types=1);
  * @copyright Copyright (c) 2020, Georg Ehrke
  *
  * @author Georg Ehrke <oc.list@georgehrke.com>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -26,6 +27,7 @@ declare(strict_types=1);
 namespace OCA\UserStatus\Controller;
 
 use OCA\UserStatus\Db\UserStatus;
+use OCA\UserStatus\ResponseDefinitions;
 use OCA\UserStatus\Service\StatusService;
 use OCP\AppFramework\Controller;
 use OCP\AppFramework\Db\DoesNotExistException;
@@ -39,6 +41,9 @@ use OCP\IUserSession;
 use OCP\User\Events\UserLiveStatusEvent;
 use OCP\UserStatus\IUserStatus;
 
+/**
+ * @psalm-import-type UserStatusPrivate from ResponseDefinitions
+ */
 class HeartbeatController extends OCSController {
 
 	/** @var IEventDispatcher */
@@ -67,10 +72,16 @@ class HeartbeatController extends OCSController {
 	}
 
 	/**
+	 * Keep the status alive
+	 *
 	 * @NoAdminRequired
 	 *
-	 * @param string $status
-	 * @return DataResponse
+	 * @param string $status Only online, away
+	 *
+	 * @return DataResponse<Http::STATUS_OK, UserStatusPrivate, array{}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_INTERNAL_SERVER_ERROR|Http::STATUS_NO_CONTENT, array<empty>, array{}>
+	 * 200: Status successfully updated
+	 * 204: User has no status to keep alive
+	 * 400: Invalid status to update
 	 */
 	public function heartbeat(string $status): DataResponse {
 		if (!\in_array($status, [IUserStatus::ONLINE, IUserStatus::AWAY], true)) {

apps/user_status/lib/Controller/PredefinedStatusController.php

@@ -6,6 +6,7 @@ declare(strict_types=1);
  * @copyright Copyright (c) 2020, Georg Ehrke
  *
  * @author Georg Ehrke <oc.list@georgehrke.com>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -25,15 +26,17 @@ declare(strict_types=1);
  */
 namespace OCA\UserStatus\Controller;
 
+use OCA\UserStatus\ResponseDefinitions;
 use OCA\UserStatus\Service\PredefinedStatusService;
+use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCSController;
 use OCP\IRequest;
 
 /**
- * Class DefaultStatusController
- *
  * @package OCA\UserStatus\Controller
+ *
+ * @psalm-import-type UserStatusPredefined from ResponseDefinitions
  */
 class PredefinedStatusController extends OCSController {
 
@@ -55,9 +58,11 @@ class PredefinedStatusController extends OCSController {
 	}
 
 	/**
+	 * Get all predefined messages
+	 *
 	 * @NoAdminRequired
 	 *
-	 * @return DataResponse
+	 * @return DataResponse<Http::STATUS_OK, UserStatusPredefined[], array{}>
 	 */
 	public function findAll():DataResponse {
 		// Filtering out the invisible one, that should only be set by API

apps/user_status/lib/Controller/StatusesController.php

@@ -7,6 +7,7 @@ declare(strict_types=1);
  *
  * @author Christoph Wurst <christoph@winzerhof-wurst.at>
  * @author Georg Ehrke <oc.list@georgehrke.com>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -27,14 +28,19 @@ declare(strict_types=1);
 namespace OCA\UserStatus\Controller;
 
 use OCA\UserStatus\Db\UserStatus;
+use OCA\UserStatus\ResponseDefinitions;
 use OCA\UserStatus\Service\StatusService;
 use OCP\AppFramework\Db\DoesNotExistException;
+use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCS\OCSNotFoundException;
 use OCP\AppFramework\OCSController;
 use OCP\IRequest;
 use OCP\UserStatus\IUserStatus;
 
+/**
+ * @psalm-import-type UserStatusPublic from ResponseDefinitions
+ */
 class StatusesController extends OCSController {
 
 	/** @var StatusService */
@@ -55,11 +61,13 @@ class StatusesController extends OCSController {
 	}
 
 	/**
+	 * Find statuses of users
+	 *
 	 * @NoAdminRequired
 	 *
-	 * @param int|null $limit
-	 * @param int|null $offset
-	 * @return DataResponse
+	 * @param int|null $limit Maximum number of statuses to find
+	 * @param int|null $offset Offset for finding statuses
+	 * @return DataResponse<Http::STATUS_OK, UserStatusPublic[], array{}>
 	 */
 	public function findAll(?int $limit = null, ?int $offset = null): DataResponse {
 		$allStatuses = $this->service->findAll($limit, $offset);
@@ -70,11 +78,15 @@ class StatusesController extends OCSController {
 	}
 
 	/**
+	 * Find the status of a user
+	 *
 	 * @NoAdminRequired
 	 *
-	 * @param string $userId
-	 * @return DataResponse
-	 * @throws OCSNotFoundException
+	 * @param string $userId ID of the user
+	 * @return DataResponse<Http::STATUS_OK, UserStatusPublic, array{}>
+	 * @throws OCSNotFoundException The user was not found
+	 *
+	 * 200: The status was found successfully
 	 */
 	public function find(string $userId): DataResponse {
 		try {
@@ -88,7 +100,7 @@ class StatusesController extends OCSController {
 
 	/**
 	 * @param UserStatus $status
-	 * @return array{userId: string, message: string, icon: string, clearAt: int, status: string}
+	 * @return UserStatusPublic
 	 */
 	private function formatStatus(UserStatus $status): array {
 		$visibleStatus = $status->getStatus();

apps/user_status/lib/Controller/UserStatusController.php

@@ -8,6 +8,7 @@ declare(strict_types=1);
  * @author Georg Ehrke <oc.list@georgehrke.com>
  * @author Joas Schilling <coding@schilljs.com>
  * @author Simon Spannagel <simonspa@kth.se>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -33,8 +34,10 @@ use OCA\UserStatus\Exception\InvalidMessageIdException;
 use OCA\UserStatus\Exception\InvalidStatusIconException;
 use OCA\UserStatus\Exception\InvalidStatusTypeException;
 use OCA\UserStatus\Exception\StatusMessageTooLongException;
+use OCA\UserStatus\ResponseDefinitions;
 use OCA\UserStatus\Service\StatusService;
 use OCP\AppFramework\Db\DoesNotExistException;
+use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCS\OCSBadRequestException;
 use OCP\AppFramework\OCS\OCSNotFoundException;
@@ -42,6 +45,9 @@ use OCP\AppFramework\OCSController;
 use OCP\ILogger;
 use OCP\IRequest;
 
+/**
+ * @psalm-import-type UserStatusPrivate from ResponseDefinitions
+ */
 class UserStatusController extends OCSController {
 
 	/** @var string */
@@ -74,10 +80,14 @@ class UserStatusController extends OCSController {
 	}
 
 	/**
+	 * Get the status of the current user
+	 *
 	 * @NoAdminRequired
 	 *
-	 * @return DataResponse
-	 * @throws OCSNotFoundException
+	 * @return DataResponse<Http::STATUS_OK, UserStatusPrivate, array{}>
+	 * @throws OCSNotFoundException The user was not found
+	 *
+	 * 200: The status was found successfully
 	 */
 	public function getStatus(): DataResponse {
 		try {
@@ -90,11 +100,15 @@ class UserStatusController extends OCSController {
 	}
 
 	/**
+	 * Update the status type of the current user
+	 *
 	 * @NoAdminRequired
 	 *
-	 * @param string $statusType
-	 * @return DataResponse
-	 * @throws OCSBadRequestException
+	 * @param string $statusType The new status type
+	 * @return DataResponse<Http::STATUS_OK, UserStatusPrivate, array{}>
+	 * @throws OCSBadRequestException The status type is invalid
+	 *
+	 * 200: The status was updated successfully
 	 */
 	public function setStatus(string $statusType): DataResponse {
 		try {
@@ -109,12 +123,16 @@ class UserStatusController extends OCSController {
 	}
 
 	/**
+	 * Set the message to a predefined message for the current user
+	 *
 	 * @NoAdminRequired
 	 *
-	 * @param string $messageId
-	 * @param int|null $clearAt
-	 * @return DataResponse
-	 * @throws OCSBadRequestException
+	 * @param string $messageId ID of the predefined message
+	 * @param int|null $clearAt When the message should be cleared
+	 * @return DataResponse<Http::STATUS_OK, UserStatusPrivate, array{}>
+	 * @throws OCSBadRequestException The clearAt or message-id is invalid
+	 *
+	 * 200: The message was updated successfully
 	 */
 	public function setPredefinedMessage(string $messageId,
 										 ?int $clearAt): DataResponse {
@@ -132,13 +150,17 @@ class UserStatusController extends OCSController {
 	}
 
 	/**
+	 * Set the message to a custom message for the current user
+	 *
 	 * @NoAdminRequired
 	 *
-	 * @param string|null $statusIcon
-	 * @param string|null $message
-	 * @param int|null $clearAt
-	 * @return DataResponse
-	 * @throws OCSBadRequestException
+	 * @param string|null $statusIcon Icon of the status
+	 * @param string|null $message Message of the status
+	 * @param int|null $clearAt When the message should be cleared
+	 * @return DataResponse<Http::STATUS_OK, UserStatusPrivate, array{}>
+	 * @throws OCSBadRequestException The clearAt or icon is invalid or the message is too long
+	 *
+	 * 200: The message was updated successfully
 	 */
 	public function setCustomMessage(?string $statusIcon,
 									 ?string $message,
@@ -165,9 +187,11 @@ class UserStatusController extends OCSController {
 	}
 
 	/**
+	 * Clear the message of the current user
+	 *
 	 * @NoAdminRequired
 	 *
-	 * @return DataResponse
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
 	 */
 	public function clearMessage(): DataResponse {
 		$this->service->clearMessage($this->userId);
@@ -175,9 +199,15 @@ class UserStatusController extends OCSController {
 	}
 
 	/**
+	 * Revert the status to the previous status
+	 *
 	 * @NoAdminRequired
 	 *
-	 * @return DataResponse
+	 * @param string $messageId ID of the message to delete
+	 *
+	 * @return DataResponse<Http::STATUS_OK, UserStatusPrivate|array<empty>, array{}>
+	 *
+	 * 200: Status reverted
 	 */
 	public function revertStatus(string $messageId): DataResponse {
 		$backupStatus = $this->service->revertUserStatus($this->userId, $messageId, true);
@@ -189,7 +219,7 @@ class UserStatusController extends OCSController {
 
 	/**
 	 * @param UserStatus $status
-	 * @return array
+	 * @return UserStatusPrivate
 	 */
 	private function formatStatus(UserStatus $status): array {
 		return [

apps/user_status/lib/Db/UserStatus.php

@@ -42,13 +42,13 @@ use OCP\AppFramework\Db\Entity;
  * @method void setStatusTimestamp(int $statusTimestamp)
  * @method bool getIsUserDefined()
  * @method void setIsUserDefined(bool $isUserDefined)
- * @method string getMessageId()
+ * @method string|null getMessageId()
  * @method void setMessageId(string|null $messageId)
- * @method string getCustomIcon()
+ * @method string|null getCustomIcon()
  * @method void setCustomIcon(string|null $customIcon)
- * @method string getCustomMessage()
+ * @method string|null getCustomMessage()
  * @method void setCustomMessage(string|null $customMessage)
- * @method int getClearAt()
+ * @method int|null getClearAt()
  * @method void setClearAt(int|null $clearAt)
  * @method setIsBackup(bool $true): void
  * @method getIsBackup(): bool

apps/user_status/lib/ResponseDefinitions.php

@@ -0,0 +1,59 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2023 Kate Döen <kate.doeen@nextcloud.com>
+ *
+ * @author Kate Döen <kate.doeen@nextcloud.com>
+ *
+ * @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/>.
+ *
+ */
+
+namespace OCA\UserStatus;
+
+/**
+ * @psalm-type UserStatusClearAtTimeType = "day"|"week"
+ *
+ * @psalm-type UserStatusClearAt = array{
+ *     type: "period"|"end-of",
+ *     time: int|UserStatusClearAtTimeType,
+ * }
+ *
+ * @psalm-type UserStatusPredefined = array{
+ *     id: string,
+ *     icon: string,
+ *     message: string,
+ *     clearAt: ?UserStatusClearAt,
+ *     visible: ?bool,
+ * }
+ *
+ * @psalm-type UserStatusPublic = array{
+ *     userId: string,
+ *     message: ?string,
+ *     icon: ?string,
+ *     clearAt: ?int,
+ *     status: string,
+ * }
+ *
+ * @psalm-type UserStatusPrivate = UserStatusPublic&array{
+ *     messageId: ?string,
+ *     messageIsPredefined: bool,
+ *     statusIsUserDefined: bool,
+ * }
+ */
+class ResponseDefinitions {
+}

apps/user_status/openapi.json

@@ -740,10 +740,7 @@
                                                 "meta": {
                                                     "$ref": "#/components/schemas/OCSMeta"
                                                 },
-                                                "data": {
-                                                    "type": "object",
-                                                    "additionalProperties": true
-                                                }
+                                                "data": {}
                                             }
                                         }
                                     }
@@ -811,8 +808,12 @@
                                                     "$ref": "#/components/schemas/OCSMeta"
                                                 },
                                                 "data": {
-                                                    "$ref": "#/components/schemas/Private",
-                                                    "nullable": true
+                                                    "oneOf": [
+                                                        {
+                                                            "$ref": "#/components/schemas/Private"
+                                                        },
+                                                        {}
+                                                    ]
                                                 }
                                             }
                                         }
@@ -890,7 +891,7 @@
         "/ocs/v2.php/apps/user_status/api/v1/heartbeat": {
             "put": {
                 "operationId": "heartbeat-heartbeat",
-                "summary": "Keep the current status alive",
+                "summary": "Keep the status alive",
                 "tags": [
                     "heartbeat"
                 ],
@@ -973,10 +974,7 @@
                                                 "meta": {
                                                     "$ref": "#/components/schemas/OCSMeta"
                                                 },
-                                                "data": {
-                                                    "type": "object",
-                                                    "additionalProperties": true
-                                                }
+                                                "data": {}
                                             }
                                         }
                                     }
@@ -1004,10 +1002,7 @@
                                                 "meta": {
                                                     "$ref": "#/components/schemas/OCSMeta"
                                                 },
-                                                "data": {
-                                                    "type": "object",
-                                                    "additionalProperties": true
-                                                }
+                                                "data": {}
                                             }
                                         }
                                     }
@@ -1035,10 +1030,7 @@
                                                 "meta": {
                                                     "$ref": "#/components/schemas/OCSMeta"
                                                 },
-                                                "data": {
-                                                    "type": "object",
-                                                    "additionalProperties": true
-                                                }
+                                                "data": {}
                                             }
                                         }
                                     }