user_status: Add OpenAPI spec

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

7 files changed, 154 insertions, 33 deletions

diff --git a/apps/user_status/lib/Capabilities.php b/apps/user_status/lib/Capabilities.php
index 67e73f2733c..85652e17b4e 100644
--- a/apps/user_status/lib/Capabilities.php
+++ b/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' => [
diff --git a/apps/user_status/lib/Controller/HeartbeatController.php b/apps/user_status/lib/Controller/HeartbeatController.php
index e0b735f044f..c2b1ed57f01 100644
--- a/apps/user_status/lib/Controller/HeartbeatController.php
+++ b/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)) {
diff --git a/apps/user_status/lib/Controller/PredefinedStatusController.php b/apps/user_status/lib/Controller/PredefinedStatusController.php
index ea1ff5209b8..0a108a56bf6 100644
--- a/apps/user_status/lib/Controller/PredefinedStatusController.php
+++ b/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
diff --git a/apps/user_status/lib/Controller/StatusesController.php b/apps/user_status/lib/Controller/StatusesController.php
index d30389e1716..0e4deca13b7 100644
--- a/apps/user_status/lib/Controller/StatusesController.php
+++ b/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();
diff --git a/apps/user_status/lib/Controller/UserStatusController.php b/apps/user_status/lib/Controller/UserStatusController.php
index 2d96cd90a40..f3757f38357 100644
--- a/apps/user_status/lib/Controller/UserStatusController.php
+++ b/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 [
diff --git a/apps/user_status/lib/Db/UserStatus.php b/apps/user_status/lib/Db/UserStatus.php
index 8907c4a2c1b..d4e24e75597 100644
--- a/apps/user_status/lib/Db/UserStatus.php
+++ b/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
diff --git a/apps/user_status/lib/ResponseDefinitions.php b/apps/user_status/lib/ResponseDefinitions.php
new file mode 100644
index 00000000000..2c20bd9f126
--- /dev/null
+++ b/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 {
+}