user_status: Add OpenAPI spec

Signed-off-by: jld3103 <jld3103yt@gmail.com>
nextcloud · Jul 4, 2023 · 6f9cf88 · 6f9cf88
1 parent 2c71a77
commit 6f9cf88
Show file tree

Hide file tree

Showing 10 changed files with 167 additions and 52 deletions.
diff --git a/apps/user_status/composer/composer/autoload_classmap.php b/apps/user_status/composer/composer/autoload_classmap.php
@@ -31,6 +31,7 @@
     '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',

diff --git a/apps/user_status/composer/composer/autoload_static.php b/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',

diff --git a/apps/user_status/lib/Capabilities.php b/apps/user_status/lib/Capabilities.php
@@ -6,6 +6,7 @@
  * @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 @@ public function __construct(IEmojiHelper $emojiHelper) {
 		$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
@@ -6,6 +6,7 @@
  * @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 @@
 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\User\Events\UserLiveStatusEvent;
 use OCP\UserStatus\IUserStatus;
 
+/**
+ * @psalm-import-type UserStatusPrivate from ResponseDefinitions
+ */
 class HeartbeatController extends OCSController {
 
 	/** @var IEventDispatcher */
@@ -67,10 +72,16 @@ public function __construct(string $appName,
 	}
 
 	/**
+	 * 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
@@ -6,6 +6,7 @@
  * @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 @@
  */
 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 @@ public function __construct(string $appName,
 	}
 
 	/**
+	 * 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
@@ -7,6 +7,7 @@
  *
  * @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 @@
 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 @@ public function __construct(string $appName,
 	}
 
 	/**
+	 * 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 @@ public function findAll(?int $limit = null, ?int $offset = null): DataResponse {
 	}
 
 	/**
+	 * 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 @@ public function find(string $userId): DataResponse {
 
 	/**
 	 * @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
@@ -8,6 +8,7 @@
  * @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,15 +34,20 @@
 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;
 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 @@ public function __construct(string $appName,
 	}
 
 	/**
+	 * 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 @@ public function getStatus(): DataResponse {
 	}
 
 	/**
+	 * 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 @@ public function setStatus(string $statusType): DataResponse {
 	}
 
 	/**
+	 * 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 @@ public function setPredefinedMessage(string $messageId,
 	}
 
 	/**
+	 * 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,19 +187,27 @@ public function setCustomMessage(?string $statusIcon,
 	}
 
 	/**
+	 * 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);
 		return new DataResponse([]);
 	}
 
 	/**
+	 * 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 @@ public function revertStatus(string $messageId): DataResponse {
 
 	/**
 	 * @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
@@ -42,13 +42,13 @@
  * @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