From 6f9cf8817c99ba3701ae075c80fd5ca740f57d19 Mon Sep 17 00:00:00 2001 From: jld3103 Date: Wed, 15 Feb 2023 19:13:57 +0100 Subject: [PATCH] user_status: Add OpenAPI spec Signed-off-by: jld3103 --- .../composer/composer/autoload_classmap.php | 1 + .../composer/composer/autoload_static.php | 1 + apps/user_status/lib/Capabilities.php | 4 ++ .../lib/Controller/HeartbeatController.php | 15 ++++- .../Controller/PredefinedStatusController.php | 11 +++- .../lib/Controller/StatusesController.php | 26 ++++++-- .../lib/Controller/UserStatusController.php | 64 ++++++++++++++----- apps/user_status/lib/Db/UserStatus.php | 8 +-- apps/user_status/lib/ResponseDefinitions.php | 59 +++++++++++++++++ apps/user_status/openapi.json | 30 ++++----- 10 files changed, 167 insertions(+), 52 deletions(-) create mode 100644 apps/user_status/lib/ResponseDefinitions.php diff --git a/apps/user_status/composer/composer/autoload_classmap.php b/apps/user_status/composer/composer/autoload_classmap.php index 9988231d76e78..7cfc131ab20b1 100644 --- 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 index 1ad125615ea02..73de6f1a0f716 100644 --- 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 index 67e73f2733caa..85652e17b4e67 100644 --- 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 + * @author Kate Döen * * @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 index e0b735f044f7b..c2b1ed57f0152 100644 --- 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 + * @author Kate Döen * * @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|DataResponse, 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 ea1ff5209b854..0a108a56bf6c8 100644 --- 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 + * @author Kate Döen * * @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 */ 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 d30389e1716c6..0e4deca13b708 100644 --- a/apps/user_status/lib/Controller/StatusesController.php +++ b/apps/user_status/lib/Controller/StatusesController.php @@ -7,6 +7,7 @@ * * @author Christoph Wurst * @author Georg Ehrke + * @author Kate Döen * * @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 */ 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 + * @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 index 2d96cd90a40d3..f3757f3835735 100644 --- a/apps/user_status/lib/Controller/UserStatusController.php +++ b/apps/user_status/lib/Controller/UserStatusController.php @@ -8,6 +8,7 @@ * @author Georg Ehrke * @author Joas Schilling * @author Simon Spannagel + * @author Kate Döen * * @license GNU AGPL version 3 or any later version * @@ -33,8 +34,10 @@ 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\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 + * @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 + * @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 + * @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 + * @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 @@ public function setCustomMessage(?string $statusIcon, } /** + * Clear the message of the current user + * * @NoAdminRequired * - * @return DataResponse + * @return DataResponse, array{}> */ public function clearMessage(): DataResponse { $this->service->clearMessage($this->userId); @@ -175,9 +199,15 @@ public function clearMessage(): DataResponse { } /** + * Revert the status to the previous status + * * @NoAdminRequired * - * @return DataResponse + * @param string $messageId ID of the message to delete + * + * @return DataResponse, 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 index 8907c4a2c1bbf..d4e24e7559772 100644 --- 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 diff --git a/apps/user_status/lib/ResponseDefinitions.php b/apps/user_status/lib/ResponseDefinitions.php new file mode 100644 index 0000000000000..2c20bd9f126c2 --- /dev/null +++ b/apps/user_status/lib/ResponseDefinitions.php @@ -0,0 +1,59 @@ + + * + * @author Kate Döen + * + * @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 . + * + */ + +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 { +} diff --git a/apps/user_status/openapi.json b/apps/user_status/openapi.json index 08eddd47bb3df..8629256942d7c 100644 --- a/apps/user_status/openapi.json +++ b/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": {} } } }