upstream/nextcloud
1
0
Fork 0
mirror of https://github.com/nextcloud/server.git synced 2026-05-28 04:32:30 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 54

user_status: Add OpenAPI spec

Browse source 
Signed-off-by: jld3103 <jld3103yt@gmail.com>
This commit is contained in:
jld3103 2023-02-15 19:13:57 +01:00
parent 2c71a77f4b
commit 6f9cf8817c
No known key found for this signature in database
GPG key ID: 9062417B9E8EB7B3
10 changed files with 167 additions and 52 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
apps/user_status/composer/composer/autoload_classmap.php
View file

@ -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',

1
apps/user_status/composer/composer/autoload_static.php
View file

@ -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',

4
apps/user_status/lib/Capabilities.php
View file

@ -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' => [

15
apps/user_status/lib/Controller/HeartbeatController.php
View file

@ -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)) {

11
apps/user_status/lib/Controller/PredefinedStatusController.php
View file

@ -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

26
apps/user_status/lib/Controller/StatusesController.php
View file

@ -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();

64
apps/user_status/lib/Controller/UserStatusController.php
View file

@ -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 [

8
apps/user_status/lib/Db/UserStatus.php
View file

@ -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

59
apps/user_status/lib/ResponseDefinitions.php Normal file
View file

@ -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 {
}

30
apps/user_status/openapi.json
View file

@ -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": {}
}
}
}