Skip to content

Commit 0253834

Browse files
provokateurinprovokateurin
committed
user_status: Add OpenAPI spec
Signed-off-by: jld3103 <[email protected]>
1 parent 9476711 commit 0253834

File tree

6 files changed

+939
-38
lines changed

6 files changed

+939
-38
lines changed

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

Lines changed: 15 additions & 11 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 <[email protected]>
9+
* @author Kate Döen <[email protected]>
910
*
1011
* @license GNU AGPL version 3 or any later version
1112
*
@@ -23,12 +24,11 @@
2324
* along with this program. If not, see <http://www.gnu.org/licenses/>.
2425
*
2526
*/
27+
2628
namespace OCA\UserStatus\Controller;
2729

2830
use OCA\UserStatus\Db\UserStatus;
2931
use OCA\UserStatus\Service\StatusService;
30-
use OCP\AppFramework\Controller;
31-
use OCP\AppFramework\Db\DoesNotExistException;
3232
use OCP\AppFramework\Http;
3333
use OCP\AppFramework\Http\DataResponse;
3434
use OCP\AppFramework\OCSController;
@@ -53,12 +53,13 @@ class HeartbeatController extends OCSController {
5353
/** @var StatusService */
5454
private $service;
5555

56-
public function __construct(string $appName,
57-
IRequest $request,
58-
IEventDispatcher $eventDispatcher,
59-
IUserSession $userSession,
60-
ITimeFactory $timeFactory,
61-
StatusService $service) {
56+
public function __construct(
57+
string $appName,
58+
IRequest $request,
59+
IEventDispatcher $eventDispatcher,
60+
IUserSession $userSession,
61+
ITimeFactory $timeFactory,
62+
StatusService $service) {
6263
parent::__construct($appName, $request);
6364
$this->eventDispatcher = $eventDispatcher;
6465
$this->userSession = $userSession;
@@ -69,11 +70,14 @@ public function __construct(string $appName,
6970
/**
7071
* @NoAdminRequired
7172
*
72-
* @param string $status
73-
* @return DataResponse
73+
* @param string $status online, away
74+
* @psalm-import-type PrivateUserStatus
75+
* @return DataResponse<PrivateUserStatus> 200 Status successfully updated
76+
* @return DataResponse 204 User has no status to update
77+
* @return DataResponse 400 Invalid status to update
7478
*/
7579
public function heartbeat(string $status): DataResponse {
76-
if (!\in_array($status, [IUserStatus::ONLINE, IUserStatus::AWAY], true)) {
80+
if (!in_array($status, [IUserStatus::ONLINE, IUserStatus::AWAY], true)) {
7781
return new DataResponse([], Http::STATUS_BAD_REQUEST);
7882
}
7983

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

Lines changed: 9 additions & 5 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 <[email protected]>
9+
* @author Kate Döen <[email protected]>
910
*
1011
* @license GNU AGPL version 3 or any later version
1112
*
@@ -23,6 +24,7 @@
2324
* along with this program. If not, see <http://www.gnu.org/licenses/>.
2425
*
2526
*/
27+
2628
namespace OCA\UserStatus\Controller;
2729

2830
use OCA\UserStatus\Service\PredefinedStatusService;
@@ -47,19 +49,21 @@ class PredefinedStatusController extends OCSController {
4749
* @param IRequest $request
4850
* @param PredefinedStatusService $predefinedStatusService
4951
*/
50-
public function __construct(string $appName,
51-
IRequest $request,
52-
PredefinedStatusService $predefinedStatusService) {
52+
public function __construct(
53+
string $appName,
54+
IRequest $request,
55+
PredefinedStatusService $predefinedStatusService) {
5356
parent::__construct($appName, $request);
5457
$this->predefinedStatusService = $predefinedStatusService;
5558
}
5659

5760
/**
5861
* @NoAdminRequired
5962
*
60-
* @return DataResponse
63+
* @psalm-import-type PredefinedStatus
64+
* @return DataResponse<PredefinedStatus[]> 200
6165
*/
62-
public function findAll():DataResponse {
66+
public function findAll(): DataResponse {
6367
// Filtering out the invisible one, that should only be set by API
6468
return new DataResponse(array_filter($this->predefinedStatusService->getDefaultStatuses(), function (array $status) {
6569
return !array_key_exists('visible', $status) || $status['visible'] === true;

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

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@
2424
* along with this program. If not, see <http://www.gnu.org/licenses/>.
2525
*
2626
*/
27+
2728
namespace OCA\UserStatus\Controller;
2829

2930
use OCA\UserStatus\Db\UserStatus;
@@ -47,9 +48,10 @@ class StatusesController extends OCSController {
4748
* @param IRequest $request
4849
* @param StatusService $service
4950
*/
50-
public function __construct(string $appName,
51-
IRequest $request,
52-
StatusService $service) {
51+
public function __construct(
52+
string $appName,
53+
IRequest $request,
54+
StatusService $service) {
5355
parent::__construct($appName, $request);
5456
$this->service = $service;
5557
}
@@ -59,7 +61,8 @@ public function __construct(string $appName,
5961
*
6062
* @param int|null $limit
6163
* @param int|null $offset
62-
* @return DataResponse
64+
* @psalm-import-type PublicUserStatus
65+
* @return DataResponse<PublicUserStatus[]> 200
6366
*/
6467
public function findAll(?int $limit = null, ?int $offset = null): DataResponse {
6568
$allStatuses = $this->service->findAll($limit, $offset);
@@ -73,7 +76,8 @@ public function findAll(?int $limit = null, ?int $offset = null): DataResponse {
7376
* @NoAdminRequired
7477
*
7578
* @param string $userId
76-
* @return DataResponse
79+
* @psalm-import-type PublicUserStatus
80+
* @return DataResponse<PublicUserStatus> 200
7781
* @throws OCSNotFoundException
7882
*/
7983
public function find(string $userId): DataResponse {
@@ -88,7 +92,7 @@ public function find(string $userId): DataResponse {
8892

8993
/**
9094
* @param UserStatus $status
91-
* @return array{userId: string, message: string, icon: string, clearAt: int, status: string}
95+
* @return array
9296
*/
9397
private function formatStatus(UserStatus $status): array {
9498
$visibleStatus = $status->getStatus();

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

Lines changed: 22 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
* @author Georg Ehrke <[email protected]>
99
* @author Joas Schilling <[email protected]>
1010
* @author Simon Spannagel <[email protected]>
11+
* @author Kate Döen <[email protected]>
1112
*
1213
* @license GNU AGPL version 3 or any later version
1314
*
@@ -25,6 +26,7 @@
2526
* along with this program. If not, see <http://www.gnu.org/licenses/>.
2627
*
2728
*/
29+
2830
namespace OCA\UserStatus\Controller;
2931

3032
use OCA\UserStatus\Db\UserStatus;
@@ -59,14 +61,15 @@ class UserStatusController extends OCSController {
5961
* @param string $appName
6062
* @param IRequest $request
6163
* @param string $userId
62-
* @param ILogger $logger;
64+
* @param ILogger $logger
6365
* @param StatusService $service
6466
*/
65-
public function __construct(string $appName,
66-
IRequest $request,
67-
string $userId,
68-
ILogger $logger,
69-
StatusService $service) {
67+
public function __construct(
68+
string $appName,
69+
IRequest $request,
70+
string $userId,
71+
ILogger $logger,
72+
StatusService $service) {
7073
parent::__construct($appName, $request);
7174
$this->userId = $userId;
7275
$this->logger = $logger;
@@ -76,7 +79,8 @@ public function __construct(string $appName,
7679
/**
7780
* @NoAdminRequired
7881
*
79-
* @return DataResponse
82+
* @psalm-import-type PrivateUserStatus
83+
* @return DataResponse<PrivateUserStatus> 200
8084
* @throws OCSNotFoundException
8185
*/
8286
public function getStatus(): DataResponse {
@@ -93,7 +97,8 @@ public function getStatus(): DataResponse {
9397
* @NoAdminRequired
9498
*
9599
* @param string $statusType
96-
* @return DataResponse
100+
* @psalm-import-type PrivateUserStatus
101+
* @return DataResponse<PrivateUserStatus> 200
97102
* @throws OCSBadRequestException
98103
*/
99104
public function setStatus(string $statusType): DataResponse {
@@ -113,11 +118,11 @@ public function setStatus(string $statusType): DataResponse {
113118
*
114119
* @param string $messageId
115120
* @param int|null $clearAt
116-
* @return DataResponse
121+
* @psalm-import-type PrivateUserStatus
122+
* @return DataResponse<PrivateUserStatus> 200
117123
* @throws OCSBadRequestException
118124
*/
119-
public function setPredefinedMessage(string $messageId,
120-
?int $clearAt): DataResponse {
125+
public function setPredefinedMessage(string $messageId, ?int $clearAt): DataResponse {
121126
try {
122127
$status = $this->service->setPredefinedMessage($this->userId, $messageId, $clearAt);
123128
$this->service->removeBackupUserStatus($this->userId);
@@ -137,12 +142,13 @@ public function setPredefinedMessage(string $messageId,
137142
* @param string|null $statusIcon
138143
* @param string|null $message
139144
* @param int|null $clearAt
140-
* @return DataResponse
145+
* @psalm-import-type PrivateUserStatus
146+
* @return DataResponse<PrivateUserStatus> 200
141147
* @throws OCSBadRequestException
142148
*/
143149
public function setCustomMessage(?string $statusIcon,
144-
?string $message,
145-
?int $clearAt): DataResponse {
150+
?string $message,
151+
?int $clearAt): DataResponse {
146152
try {
147153
if (($message !== null && $message !== '') || ($clearAt !== null && $clearAt !== 0)) {
148154
$status = $this->service->setCustomMessage($this->userId, $statusIcon, $message, $clearAt);
@@ -167,7 +173,7 @@ public function setCustomMessage(?string $statusIcon,
167173
/**
168174
* @NoAdminRequired
169175
*
170-
* @return DataResponse
176+
* @return DataResponse 200
171177
*/
172178
public function clearStatus(): DataResponse {
173179
$this->service->clearStatus($this->userId);
@@ -177,7 +183,7 @@ public function clearStatus(): DataResponse {
177183
/**
178184
* @NoAdminRequired
179185
*
180-
* @return DataResponse
186+
* @return DataResponse 200
181187
*/
182188
public function clearMessage(): DataResponse {
183189
$this->service->clearMessage($this->userId);

‎apps/user_status/lib/ResponseDefinitions.php‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
<?php
2+
declare(strict_types=1);
3+
4+
/**
5+
* @copyright Copyright (c) 2023 Kate Döen <[email protected]>
6+
*
7+
* @author Kate Döen <[email protected]>
8+
*
9+
* @license GNU AGPL version 3 or any later version
10+
*
11+
* This program is free software: you can redistribute it and/or modify
12+
* it under the terms of the GNU Affero General Public License as
13+
* published by the Free Software Foundation, either version 3 of the
14+
* License, or (at your option) any later version.
15+
*
16+
* This program is distributed in the hope that it will be useful,
17+
* but WITHOUT ANY WARRANTY; without even the implied warranty of
18+
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19+
* GNU Affero General Public License for more details.
20+
*
21+
* You should have received a copy of the GNU Affero General Public License
22+
* along with this program. If not, see <http://www.gnu.org/licenses/>.
23+
*
24+
*/
25+
26+
namespace OCA\UserStatus;
27+
28+
/**
29+
* @psalm-type ClearAt = array{
30+
* type: string,
31+
* time: string|int,
32+
* }
33+
*
34+
* @psalm-type PredefinedStatus = array{
35+
* id: string,
36+
* icon: string,
37+
* message: string,
38+
* clearAt: ClearAt|null,
39+
* visible: bool|null,
40+
* }
41+
*
42+
* @psalm-type PublicUserStatus = array{
43+
* userId: string,
44+
* message: string|null,
45+
* icon: string|null,
46+
* clearAt: int|ClearAt|null,
47+
* status: string,
48+
* }
49+
*
50+
* @psalm-type PrivateUserStatus = PublicUserStatus&array{
51+
* messageId: string|null,
52+
* messageIsPredefined: bool,
53+
* statusIsUserDefined: bool,
54+
* }
55+
*/
56+
class ResponseDefinitions {
57+
}

0 commit comments

Comments
 (0)