Skip to content

Commit 9bf6911

Browse files
blizzzblizzz
authored
Merge pull request #39133 from nextcloud/feature/openapi/user_status
user_status: Add OpenAPI spec
2 parents a9ba19d + 6f9cf88 commit 9bf6911

File tree

10 files changed

+167
-52
lines changed

10 files changed

+167
-52
lines changed

‎apps/user_status/composer/composer/autoload_classmap.php‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
'OCA\\UserStatus\\Migration\\Version0002Date20200902144824' => $baseDir . '/../lib/Migration/Version0002Date20200902144824.php',
3232
'OCA\\UserStatus\\Migration\\Version1000Date20201111130204' => $baseDir . '/../lib/Migration/Version1000Date20201111130204.php',
3333
'OCA\\UserStatus\\Migration\\Version2301Date20210809144824' => $baseDir . '/../lib/Migration/Version2301Date20210809144824.php',
34+
'OCA\\UserStatus\\ResponseDefinitions' => $baseDir . '/../lib/ResponseDefinitions.php',
3435
'OCA\\UserStatus\\Service\\JSDataService' => $baseDir . '/../lib/Service/JSDataService.php',
3536
'OCA\\UserStatus\\Service\\PredefinedStatusService' => $baseDir . '/../lib/Service/PredefinedStatusService.php',
3637
'OCA\\UserStatus\\Service\\StatusService' => $baseDir . '/../lib/Service/StatusService.php',

‎apps/user_status/composer/composer/autoload_static.php‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ class ComposerStaticInitUserStatus
4646
'OCA\\UserStatus\\Migration\\Version0002Date20200902144824' => __DIR__ . '/..' . '/../lib/Migration/Version0002Date20200902144824.php',
4747
'OCA\\UserStatus\\Migration\\Version1000Date20201111130204' => __DIR__ . '/..' . '/../lib/Migration/Version1000Date20201111130204.php',
4848
'OCA\\UserStatus\\Migration\\Version2301Date20210809144824' => __DIR__ . '/..' . '/../lib/Migration/Version2301Date20210809144824.php',
49+
'OCA\\UserStatus\\ResponseDefinitions' => __DIR__ . '/..' . '/../lib/ResponseDefinitions.php',
4950
'OCA\\UserStatus\\Service\\JSDataService' => __DIR__ . '/..' . '/../lib/Service/JSDataService.php',
5051
'OCA\\UserStatus\\Service\\PredefinedStatusService' => __DIR__ . '/..' . '/../lib/Service/PredefinedStatusService.php',
5152
'OCA\\UserStatus\\Service\\StatusService' => __DIR__ . '/..' . '/../lib/Service/StatusService.php',

‎apps/user_status/lib/Capabilities.php‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
* @copyright Copyright (c) 2020, Georg Ehrke
77
*
88
* @author Georg Ehrke <oc.list@georgehrke.com>
9+
* @author Kate Döen <kate.doeen@nextcloud.com>
910
*
1011
* @license GNU AGPL version 3 or any later version
1112
*
@@ -40,6 +41,9 @@ public function __construct(IEmojiHelper $emojiHelper) {
4041
$this->emojiHelper = $emojiHelper;
4142
}
4243

44+
/**
45+
* @return array{user_status: array{enabled: bool, restore: bool, supports_emoji: bool}}
46+
*/
4347
public function getCapabilities() {
4448
return [
4549
'user_status' => [

‎apps/user_status/lib/Controller/HeartbeatController.php‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
* @copyright Copyright (c) 2020, Georg Ehrke
77
*
88
* @author Georg Ehrke <oc.list@georgehrke.com>
9+
* @author Kate Döen <kate.doeen@nextcloud.com>
910
*
1011
* @license GNU AGPL version 3 or any later version
1112
*
@@ -26,6 +27,7 @@
2627
namespace OCA\UserStatus\Controller;
2728

2829
use OCA\UserStatus\Db\UserStatus;
30+
use OCA\UserStatus\ResponseDefinitions;
2931
use OCA\UserStatus\Service\StatusService;
3032
use OCP\AppFramework\Controller;
3133
use OCP\AppFramework\Db\DoesNotExistException;
@@ -39,6 +41,9 @@
3941
use OCP\User\Events\UserLiveStatusEvent;
4042
use OCP\UserStatus\IUserStatus;
4143

44+
/**
45+
* @psalm-import-type UserStatusPrivate from ResponseDefinitions
46+
*/
4247
class HeartbeatController extends OCSController {
4348

4449
/** @var IEventDispatcher */
@@ -67,10 +72,16 @@ public function __construct(string $appName,
6772
}
6873

6974
/**
75+
* Keep the status alive
76+
*
7077
* @NoAdminRequired
7178
*
72-
* @param string $status
73-
* @return DataResponse
79+
* @param string $status Only online, away
80+
*
81+
* @return DataResponse<Http::STATUS_OK, UserStatusPrivate, array{}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_INTERNAL_SERVER_ERROR|Http::STATUS_NO_CONTENT, array<empty>, array{}>
82+
* 200: Status successfully updated
83+
* 204: User has no status to keep alive
84+
* 400: Invalid status to update
7485
*/
7586
public function heartbeat(string $status): DataResponse {
7687
if (!\in_array($status, [IUserStatus::ONLINE, IUserStatus::AWAY], true)) {

‎apps/user_status/lib/Controller/PredefinedStatusController.php‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
* @copyright Copyright (c) 2020, Georg Ehrke
77
*
88
* @author Georg Ehrke <oc.list@georgehrke.com>
9+
* @author Kate Döen <kate.doeen@nextcloud.com>
910
*
1011
* @license GNU AGPL version 3 or any later version
1112
*
@@ -25,15 +26,17 @@
2526
*/
2627
namespace OCA\UserStatus\Controller;
2728

29+
use OCA\UserStatus\ResponseDefinitions;
2830
use OCA\UserStatus\Service\PredefinedStatusService;
31+
use OCP\AppFramework\Http;
2932
use OCP\AppFramework\Http\DataResponse;
3033
use OCP\AppFramework\OCSController;
3134
use OCP\IRequest;
3235

3336
/**
34-
* Class DefaultStatusController
35-
*
3637
* @package OCA\UserStatus\Controller
38+
*
39+
* @psalm-import-type UserStatusPredefined from ResponseDefinitions
3740
*/
3841
class PredefinedStatusController extends OCSController {
3942

@@ -55,9 +58,11 @@ public function __construct(string $appName,
5558
}
5659

5760
/**
61+
* Get all predefined messages
62+
*
5863
* @NoAdminRequired
5964
*
60-
* @return DataResponse
65+
* @return DataResponse<Http::STATUS_OK, UserStatusPredefined[], array{}>
6166
*/
6267
public function findAll():DataResponse {
6368
// Filtering out the invisible one, that should only be set by API

‎apps/user_status/lib/Controller/StatusesController.php‎

Lines changed: 19 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
*
88
* @author Christoph Wurst <christoph@winzerhof-wurst.at>
99
* @author Georg Ehrke <oc.list@georgehrke.com>
10+
* @author Kate Döen <kate.doeen@nextcloud.com>
1011
*
1112
* @license GNU AGPL version 3 or any later version
1213
*
@@ -27,14 +28,19 @@
2728
namespace OCA\UserStatus\Controller;
2829

2930
use OCA\UserStatus\Db\UserStatus;
31+
use OCA\UserStatus\ResponseDefinitions;
3032
use OCA\UserStatus\Service\StatusService;
3133
use OCP\AppFramework\Db\DoesNotExistException;
34+
use OCP\AppFramework\Http;
3235
use OCP\AppFramework\Http\DataResponse;
3336
use OCP\AppFramework\OCS\OCSNotFoundException;
3437
use OCP\AppFramework\OCSController;
3538
use OCP\IRequest;
3639
use OCP\UserStatus\IUserStatus;
3740

41+
/**
42+
* @psalm-import-type UserStatusPublic from ResponseDefinitions
43+
*/
3844
class StatusesController extends OCSController {
3945

4046
/** @var StatusService */
@@ -55,11 +61,13 @@ public function __construct(string $appName,
5561
}
5662

5763
/**
64+
* Find statuses of users
65+
*
5866
* @NoAdminRequired
5967
*
60-
* @param int|null $limit
61-
* @param int|null $offset
62-
* @return DataResponse
68+
* @param int|null $limit Maximum number of statuses to find
69+
* @param int|null $offset Offset for finding statuses
70+
* @return DataResponse<Http::STATUS_OK, UserStatusPublic[], array{}>
6371
*/
6472
public function findAll(?int $limit = null, ?int $offset = null): DataResponse {
6573
$allStatuses = $this->service->findAll($limit, $offset);
@@ -70,11 +78,15 @@ public function findAll(?int $limit = null, ?int $offset = null): DataResponse {
7078
}
7179

7280
/**
81+
* Find the status of a user
82+
*
7383
* @NoAdminRequired
7484
*
75-
* @param string $userId
76-
* @return DataResponse
77-
* @throws OCSNotFoundException
85+
* @param string $userId ID of the user
86+
* @return DataResponse<Http::STATUS_OK, UserStatusPublic, array{}>
87+
* @throws OCSNotFoundException The user was not found
88+
*
89+
* 200: The status was found successfully
7890
*/
7991
public function find(string $userId): DataResponse {
8092
try {
@@ -88,7 +100,7 @@ public function find(string $userId): DataResponse {
88100

89101
/**
90102
* @param UserStatus $status
91-
* @return array{userId: string, message: string, icon: string, clearAt: int, status: string}
103+
* @return UserStatusPublic
92104
*/
93105
private function formatStatus(UserStatus $status): array {
94106
$visibleStatus = $status->getStatus();

‎apps/user_status/lib/Controller/UserStatusController.php‎

Lines changed: 47 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
* @author Georg Ehrke <oc.list@georgehrke.com>
99
* @author Joas Schilling <coding@schilljs.com>
1010
* @author Simon Spannagel <simonspa@kth.se>
11+
* @author Kate Döen <kate.doeen@nextcloud.com>
1112
*
1213
* @license GNU AGPL version 3 or any later version
1314
*
@@ -33,15 +34,20 @@
3334
use OCA\UserStatus\Exception\InvalidStatusIconException;
3435
use OCA\UserStatus\Exception\InvalidStatusTypeException;
3536
use OCA\UserStatus\Exception\StatusMessageTooLongException;
37+
use OCA\UserStatus\ResponseDefinitions;
3638
use OCA\UserStatus\Service\StatusService;
3739
use OCP\AppFramework\Db\DoesNotExistException;
40+
use OCP\AppFramework\Http;
3841
use OCP\AppFramework\Http\DataResponse;
3942
use OCP\AppFramework\OCS\OCSBadRequestException;
4043
use OCP\AppFramework\OCS\OCSNotFoundException;
4144
use OCP\AppFramework\OCSController;
4245
use OCP\ILogger;
4346
use OCP\IRequest;
4447

48+
/**
49+
* @psalm-import-type UserStatusPrivate from ResponseDefinitions
50+
*/
4551
class UserStatusController extends OCSController {
4652

4753
/** @var string */
@@ -74,10 +80,14 @@ public function __construct(string $appName,
7480
}
7581

7682
/**
83+
* Get the status of the current user
84+
*
7785
* @NoAdminRequired
7886
*
79-
* @return DataResponse
80-
* @throws OCSNotFoundException
87+
* @return DataResponse<Http::STATUS_OK, UserStatusPrivate, array{}>
88+
* @throws OCSNotFoundException The user was not found
89+
*
90+
* 200: The status was found successfully
8191
*/
8292
public function getStatus(): DataResponse {
8393
try {
@@ -90,11 +100,15 @@ public function getStatus(): DataResponse {
90100
}
91101

92102
/**
103+
* Update the status type of the current user
104+
*
93105
* @NoAdminRequired
94106
*
95-
* @param string $statusType
96-
* @return DataResponse
97-
* @throws OCSBadRequestException
107+
* @param string $statusType The new status type
108+
* @return DataResponse<Http::STATUS_OK, UserStatusPrivate, array{}>
109+
* @throws OCSBadRequestException The status type is invalid
110+
*
111+
* 200: The status was updated successfully
98112
*/
99113
public function setStatus(string $statusType): DataResponse {
100114
try {
@@ -109,12 +123,16 @@ public function setStatus(string $statusType): DataResponse {
109123
}
110124

111125
/**
126+
* Set the message to a predefined message for the current user
127+
*
112128
* @NoAdminRequired
113129
*
114-
* @param string $messageId
115-
* @param int|null $clearAt
116-
* @return DataResponse
117-
* @throws OCSBadRequestException
130+
* @param string $messageId ID of the predefined message
131+
* @param int|null $clearAt When the message should be cleared
132+
* @return DataResponse<Http::STATUS_OK, UserStatusPrivate, array{}>
133+
* @throws OCSBadRequestException The clearAt or message-id is invalid
134+
*
135+
* 200: The message was updated successfully
118136
*/
119137
public function setPredefinedMessage(string $messageId,
120138
?int $clearAt): DataResponse {
@@ -132,13 +150,17 @@ public function setPredefinedMessage(string $messageId,
132150
}
133151

134152
/**
153+
* Set the message to a custom message for the current user
154+
*
135155
* @NoAdminRequired
136156
*
137-
* @param string|null $statusIcon
138-
* @param string|null $message
139-
* @param int|null $clearAt
140-
* @return DataResponse
141-
* @throws OCSBadRequestException
157+
* @param string|null $statusIcon Icon of the status
158+
* @param string|null $message Message of the status
159+
* @param int|null $clearAt When the message should be cleared
160+
* @return DataResponse<Http::STATUS_OK, UserStatusPrivate, array{}>
161+
* @throws OCSBadRequestException The clearAt or icon is invalid or the message is too long
162+
*
163+
* 200: The message was updated successfully
142164
*/
143165
public function setCustomMessage(?string $statusIcon,
144166
?string $message,
@@ -165,19 +187,27 @@ public function setCustomMessage(?string $statusIcon,
165187
}
166188

167189
/**
190+
* Clear the message of the current user
191+
*
168192
* @NoAdminRequired
169193
*
170-
* @return DataResponse
194+
* @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
171195
*/
172196
public function clearMessage(): DataResponse {
173197
$this->service->clearMessage($this->userId);
174198
return new DataResponse([]);
175199
}
176200

177201
/**
202+
* Revert the status to the previous status
203+
*
178204
* @NoAdminRequired
179205
*
180-
* @return DataResponse
206+
* @param string $messageId ID of the message to delete
207+
*
208+
* @return DataResponse<Http::STATUS_OK, UserStatusPrivate|array<empty>, array{}>
209+
*
210+
* 200: Status reverted
181211
*/
182212
public function revertStatus(string $messageId): DataResponse {
183213
$backupStatus = $this->service->revertUserStatus($this->userId, $messageId, true);
@@ -189,7 +219,7 @@ public function revertStatus(string $messageId): DataResponse {
189219

190220
/**
191221
* @param UserStatus $status
192-
* @return array
222+
* @return UserStatusPrivate
193223
*/
194224
private function formatStatus(UserStatus $status): array {
195225
return [

‎apps/user_status/lib/Db/UserStatus.php‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -42,13 +42,13 @@
4242
* @method void setStatusTimestamp(int $statusTimestamp)
4343
* @method bool getIsUserDefined()
4444
* @method void setIsUserDefined(bool $isUserDefined)
45-
* @method string getMessageId()
45+
* @method string|null getMessageId()
4646
* @method void setMessageId(string|null $messageId)
47-
* @method string getCustomIcon()
47+
* @method string|null getCustomIcon()
4848
* @method void setCustomIcon(string|null $customIcon)
49-
* @method string getCustomMessage()
49+
* @method string|null getCustomMessage()
5050
* @method void setCustomMessage(string|null $customMessage)
51-
* @method int getClearAt()
51+
* @method int|null getClearAt()
5252
* @method void setClearAt(int|null $clearAt)
5353
* @method setIsBackup(bool $true): void
5454
* @method getIsBackup(): bool

0 commit comments

Comments
 (0)