Skip to content

Commit

Permalink
Merge pull request #39133 from nextcloud/feature/openapi/user_status
Browse files Browse the repository at this point in the history
user_status: Add OpenAPI spec
  • Loading branch information
blizzz authored Jul 7, 2023
2 parents a9ba19d + 6f9cf88 commit 9bf6911
Show file tree
Hide file tree
Showing 10 changed files with 167 additions and 52 deletions.
1 change: 1 addition & 0 deletions apps/user_status/composer/composer/autoload_classmap.php
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
1 change: 1 addition & 0 deletions apps/user_status/composer/composer/autoload_static.php
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
4 changes: 4 additions & 0 deletions apps/user_status/lib/Capabilities.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
*
Expand Down Expand Up @@ -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' => [
Expand Down
15 changes: 13 additions & 2 deletions apps/user_status/lib/Controller/HeartbeatController.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
*
Expand All @@ -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;
Expand All @@ -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 */
Expand Down Expand Up @@ -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)) {
Expand Down
11 changes: 8 additions & 3 deletions apps/user_status/lib/Controller/PredefinedStatusController.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
*
Expand All @@ -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 {

Expand All @@ -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
Expand Down
26 changes: 19 additions & 7 deletions apps/user_status/lib/Controller/StatusesController.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
*
Expand All @@ -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 */
Expand All @@ -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);
Expand All @@ -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 {
Expand All @@ -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();
Expand Down
64 changes: 47 additions & 17 deletions apps/user_status/lib/Controller/UserStatusController.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
*
Expand All @@ -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 */
Expand Down Expand Up @@ -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 {
Expand All @@ -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 {
Expand All @@ -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 {
Expand All @@ -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,
Expand All @@ -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);
Expand All @@ -189,7 +219,7 @@ public function revertStatus(string $messageId): DataResponse {

/**
* @param UserStatus $status
* @return array
* @return UserStatusPrivate
*/
private function formatStatus(UserStatus $status): array {
return [
Expand Down
8 changes: 4 additions & 4 deletions apps/user_status/lib/Db/UserStatus.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading

0 comments on commit 9bf6911

Please sign in to comment.