Skip to content

Commit ce0ce11

Browse files
provokateurinprovokateurin
committed
provisioning_api: Add OpenAPI spec
Signed-off-by: jld3103 <jld3103yt@gmail.com>
1 parent 28ea62a commit ce0ce11

8 files changed

+3712
-51
lines changed

‎apps/provisioning_api/lib/Controller/AUserData.php

+7-3
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@
3636
use OC\User\Backend;
3737
use OC\User\NoUserException;
3838
use OC_Helper;
39+
use OCA\Provisioning_API\ResponseDefinitions;
3940
use OCP\Accounts\IAccountManager;
4041
use OCP\Accounts\PropertyDoesNotExistException;
4142
use OCP\AppFramework\Http;
@@ -52,6 +53,9 @@
5253
use OCP\User\Backend\ISetDisplayNameBackend;
5354
use OCP\User\Backend\ISetPasswordBackend;
5455

56+
/**
57+
* @psalm-import-type UserDetails from ResponseDefinitions
58+
*/
5559
abstract class AUserData extends OCSController {
5660
public const SCOPE_SUFFIX = 'Scope';
5761

@@ -98,12 +102,12 @@ public function __construct(string $appName,
98102
*
99103
* @param string $userId
100104
* @param bool $includeScopes
101-
* @return array
105+
* @return UserDetails|null
102106
* @throws NotFoundException
103107
* @throws OCSException
104108
* @throws OCSNotFoundException
105109
*/
106-
protected function getUserData(string $userId, bool $includeScopes = false): array {
110+
protected function getUserData(string $userId, bool $includeScopes = false): ?array {
107111
$currentLoggedInUser = $this->userSession->getUser();
108112
assert($currentLoggedInUser !== null, 'No user logged in');
109113

@@ -122,7 +126,7 @@ protected function getUserData(string $userId, bool $includeScopes = false): arr
122126
} else {
123127
// Check they are looking up themselves
124128
if ($currentLoggedInUser->getUID() !== $targetUserObject->getUID()) {
125-
return $data;
129+
return null;
126130
}
127131
}
128132

‎apps/provisioning_api/lib/Controller/AppConfigController.php

+6-5
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
*
88
* @author Joas Schilling <coding@schilljs.com>
99
* @author Roeland Jago Douma <roeland@famdouma.nl>
10+
* @author Kate Döen <kate.doeen@nextcloud.com>
1011
*
1112
* @license GNU AGPL version 3 or any later version
1213
*
@@ -84,7 +85,7 @@ public function __construct(string $appName,
8485
}
8586

8687
/**
87-
* @return DataResponse
88+
* @return DataResponse<array{data: string[]}, Http::STATUS_OK>
8889
*/
8990
public function getApps(): DataResponse {
9091
return new DataResponse([
@@ -94,7 +95,7 @@ public function getApps(): DataResponse {
9495

9596
/**
9697
* @param string $app
97-
* @return DataResponse
98+
* @return DataResponse<array{data: string[]}, Http::STATUS_OK>|DataResponse<array{data: array{message: string}}, Http::STATUS_FORBIDDEN>
9899
*/
99100
public function getKeys(string $app): DataResponse {
100101
try {
@@ -111,7 +112,7 @@ public function getKeys(string $app): DataResponse {
111112
* @param string $app
112113
* @param string $key
113114
* @param string $defaultValue
114-
* @return DataResponse
115+
* @return DataResponse<array{data: string}, Http::STATUS_OK>|DataResponse<array{data: array{message: string}}, Http::STATUS_FORBIDDEN>
115116
*/
116117
public function getValue(string $app, string $key, string $defaultValue = ''): DataResponse {
117118
try {
@@ -131,7 +132,7 @@ public function getValue(string $app, string $key, string $defaultValue = ''): D
131132
* @param string $app
132133
* @param string $key
133134
* @param string $value
134-
* @return DataResponse
135+
* @return DataResponse<array, Http::STATUS_OK>|DataResponse<array{data: array{message: string}}, Http::STATUS_FORBIDDEN>
135136
*/
136137
public function setValue(string $app, string $key, string $value): DataResponse {
137138
$user = $this->userSession->getUser();
@@ -158,7 +159,7 @@ public function setValue(string $app, string $key, string $value): DataResponse
158159
* @PasswordConfirmationRequired
159160
* @param string $app
160161
* @param string $key
161-
* @return DataResponse
162+
* @return DataResponse<array, Http::STATUS_OK>|DataResponse<array{data: array{message: string}}, Http::STATUS_FORBIDDEN>
162163
*/
163164
public function deleteKey(string $app, string $key): DataResponse {
164165
try {

‎apps/provisioning_api/lib/Controller/AppsController.php

+11-4
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
* @author Lukas Reschke <lukas@statuscode.ch>
1111
* @author Roeland Jago Douma <roeland@famdouma.nl>
1212
* @author Tom Needham <tom@owncloud.com>
13+
* @author Kate Döen <kate.doeen@nextcloud.com>
1314
*
1415
* @license AGPL-3.0
1516
*
@@ -29,13 +30,18 @@
2930
namespace OCA\Provisioning_API\Controller;
3031

3132
use OC_App;
33+
use OCA\Provisioning_API\ResponseDefinitions;
3234
use OCP\App\AppPathNotFoundException;
3335
use OCP\App\IAppManager;
36+
use OCP\AppFramework\Http;
3437
use OCP\AppFramework\Http\DataResponse;
3538
use OCP\AppFramework\OCS\OCSException;
3639
use OCP\AppFramework\OCSController;
3740
use OCP\IRequest;
3841

42+
/**
43+
* @psalm-import-type AppInfo from ResponseDefinitions
44+
*/
3945
class AppsController extends OCSController {
4046
/** @var IAppManager */
4147
private $appManager;
@@ -52,11 +58,12 @@ public function __construct(
5258

5359
/**
5460
* @param string|null $filter
55-
* @return DataResponse
61+
* @return DataResponse<array{apps: string[]}, Http::STATUS_OK>
5662
* @throws OCSException
5763
*/
5864
public function getApps(string $filter = null): DataResponse {
5965
$apps = (new OC_App())->listAllApps();
66+
/** @var string[] $list */
6067
$list = [];
6168
foreach ($apps as $app) {
6269
$list[] = $app['id'];
@@ -81,7 +88,7 @@ public function getApps(string $filter = null): DataResponse {
8188

8289
/**
8390
* @param string $app
84-
* @return DataResponse
91+
* @return DataResponse<AppInfo, Http::STATUS_OK>
8592
* @throws OCSException
8693
*/
8794
public function getAppInfo(string $app): DataResponse {
@@ -96,7 +103,7 @@ public function getAppInfo(string $app): DataResponse {
96103
/**
97104
* @PasswordConfirmationRequired
98105
* @param string $app
99-
* @return DataResponse
106+
* @return DataResponse<array, Http::STATUS_OK>
100107
* @throws OCSException
101108
*/
102109
public function enable(string $app): DataResponse {
@@ -111,7 +118,7 @@ public function enable(string $app): DataResponse {
111118
/**
112119
* @PasswordConfirmationRequired
113120
* @param string $app
114-
* @return DataResponse
121+
* @return DataResponse<array, Http::STATUS_OK>
115122
*/
116123
public function disable(string $app): DataResponse {
117124
$this->appManager->disableApp($app);

‎apps/provisioning_api/lib/Controller/GroupsController.php

+22-10
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
* @author Robin Appelman <robin@icewind.nl>
1515
* @author Roeland Jago Douma <roeland@famdouma.nl>
1616
* @author Tom Needham <tom@owncloud.com>
17+
* @author Kate Döen <kate.doeen@nextcloud.com>
1718
*
1819
* @license AGPL-3.0
1920
*
@@ -32,7 +33,9 @@
3233
*/
3334
namespace OCA\Provisioning_API\Controller;
3435

36+
use OCA\Provisioning_API\ResponseDefinitions;
3537
use OCP\Accounts\IAccountManager;
38+
use OCP\AppFramework\Http;
3639
use OCP\AppFramework\Http\DataResponse;
3740
use OCP\AppFramework\OCS\OCSException;
3841
use OCP\AppFramework\OCS\OCSForbiddenException;
@@ -48,6 +51,10 @@
4851
use OCP\L10N\IFactory;
4952
use Psr\Log\LoggerInterface;
5053

54+
/**
55+
* @psalm-import-type GroupDetails from ResponseDefinitions
56+
* @psalm-import-type UserDetails from ResponseDefinitions
57+
*/
5158
class GroupsController extends AUserData {
5259

5360
/** @var LoggerInterface */
@@ -83,7 +90,7 @@ public function __construct(string $appName,
8390
* @param string $search
8491
* @param int $limit
8592
* @param int $offset
86-
* @return DataResponse
93+
* @return DataResponse<array{groups: string[]}, Http::STATUS_OK>
8794
*/
8895
public function getGroups(string $search = '', int $limit = null, int $offset = 0): DataResponse {
8996
$groups = $this->groupManager->search($search, $limit, $offset);
@@ -104,7 +111,7 @@ public function getGroups(string $search = '', int $limit = null, int $offset =
104111
* @param string $search
105112
* @param int $limit
106113
* @param int $offset
107-
* @return DataResponse
114+
* @return DataResponse<array{groups: GroupDetails[]}, Http::STATUS_OK>
108115
*/
109116
public function getGroupsDetails(string $search = '', int $limit = null, int $offset = 0): DataResponse {
110117
$groups = $this->groupManager->search($search, $limit, $offset);
@@ -127,7 +134,7 @@ public function getGroupsDetails(string $search = '', int $limit = null, int $of
127134
* @NoAdminRequired
128135
*
129136
* @param string $groupId
130-
* @return DataResponse
137+
* @return DataResponse<array{users: string[]}, Http::STATUS_OK>
131138
* @throws OCSException
132139
*
133140
* @deprecated 14 Use getGroupUsers
@@ -142,8 +149,10 @@ public function getGroup(string $groupId): DataResponse {
142149
* @NoAdminRequired
143150
*
144151
* @param string $groupId
145-
* @return DataResponse
152+
* @return DataResponse<array{users: string[]}, Http::STATUS_OK>
146153
* @throws OCSException
154+
* @throws OCSNotFoundException
155+
* @throws OCSForbiddenException
147156
*/
148157
public function getGroupUsers(string $groupId): DataResponse {
149158
$groupId = urldecode($groupId);
@@ -167,6 +176,7 @@ public function getGroupUsers(string $groupId): DataResponse {
167176
/** @var IUser $user */
168177
return $user->getUID();
169178
}, $users);
179+
/** @var string[] $users */
170180
$users = array_values($users);
171181
return new DataResponse(['users' => $users]);
172182
}
@@ -183,7 +193,8 @@ public function getGroupUsers(string $groupId): DataResponse {
183193
* @param string $search
184194
* @param int $limit
185195
* @param int $offset
186-
* @return DataResponse
196+
*
197+
* @return DataResponse<array{users: array<string, UserDetails|array{id: string}>}, Http::STATUS_OK>
187198
* @throws OCSException
188199
*/
189200
public function getGroupUsersDetails(string $groupId, string $search = '', int $limit = null, int $offset = 0): DataResponse {
@@ -210,7 +221,7 @@ public function getGroupUsersDetails(string $groupId, string $search = '', int $
210221
$userId = (string)$user->getUID();
211222
$userData = $this->getUserData($userId);
212223
// Do not insert empty entry
213-
if (!empty($userData)) {
224+
if ($userData != null) {
214225
$usersDetails[$userId] = $userData;
215226
} else {
216227
// Logged user does not have permissions to see this user
@@ -234,7 +245,7 @@ public function getGroupUsersDetails(string $groupId, string $search = '', int $
234245
*
235246
* @param string $groupid
236247
* @param string $displayname
237-
* @return DataResponse
248+
* @return DataResponse<array, Http::STATUS_OK>
238249
* @throws OCSException
239250
*/
240251
public function addGroup(string $groupid, string $displayname = ''): DataResponse {
@@ -263,7 +274,7 @@ public function addGroup(string $groupid, string $displayname = ''): DataRespons
263274
* @param string $groupId
264275
* @param string $key
265276
* @param string $value
266-
* @return DataResponse
277+
* @return DataResponse<array, Http::STATUS_OK>
267278
* @throws OCSException
268279
*/
269280
public function updateGroup(string $groupId, string $key, string $value): DataResponse {
@@ -285,7 +296,7 @@ public function updateGroup(string $groupId, string $key, string $value): DataRe
285296
* @PasswordConfirmationRequired
286297
*
287298
* @param string $groupId
288-
* @return DataResponse
299+
* @return DataResponse<array, Http::STATUS_OK>
289300
* @throws OCSException
290301
*/
291302
public function deleteGroup(string $groupId): DataResponse {
@@ -304,7 +315,7 @@ public function deleteGroup(string $groupId): DataResponse {
304315

305316
/**
306317
* @param string $groupId
307-
* @return DataResponse
318+
* @return DataResponse<string[], Http::STATUS_OK>
308319
* @throws OCSException
309320
*/
310321
public function getSubAdminsOfGroup(string $groupId): DataResponse {
@@ -317,6 +328,7 @@ public function getSubAdminsOfGroup(string $groupId): DataResponse {
317328
/** @var IUser[] $subadmins */
318329
$subadmins = $this->groupManager->getSubAdmin()->getGroupsSubAdmins($targetGroup);
319330
// New class returns IUser[] so convert back
331+
/** @var string[] $uids */
320332
$uids = [];
321333
foreach ($subadmins as $user) {
322334
$uids[] = $user->getUID();

‎apps/provisioning_api/lib/Controller/PreferencesController.php

+13
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
* @copyright Copyright (c) 2022 Joas Schilling <coding@schilljs.com>
77
*
88
* @author Joas Schilling <coding@schilljs.com>
9+
* @author Kate Döen <kate.doeen@nextcloud.com>
910
*
1011
* @license GNU AGPL version 3 or any later version
1112
*
@@ -58,6 +59,10 @@ public function __construct(
5859
/**
5960
* @NoAdminRequired
6061
* @NoSubAdminRequired
62+
*
63+
* @param array<string, string> $configs
64+
*
65+
* @return DataResponse<array, Http::STATUS_OK|Http::STATUS_BAD_REQUEST>
6166
*/
6267
public function setMultiplePreferences(string $appId, array $configs): DataResponse {
6368
$userId = $this->userSession->getUser()->getUID();
@@ -93,6 +98,8 @@ public function setMultiplePreferences(string $appId, array $configs): DataRespo
9398
/**
9499
* @NoAdminRequired
95100
* @NoSubAdminRequired
101+
*
102+
* @return DataResponse<array, Http::STATUS_OK|Http::STATUS_BAD_REQUEST>
96103
*/
97104
public function setPreference(string $appId, string $configKey, string $configValue): DataResponse {
98105
$userId = $this->userSession->getUser()->getUID();
@@ -124,6 +131,10 @@ public function setPreference(string $appId, string $configKey, string $configVa
124131
/**
125132
* @NoAdminRequired
126133
* @NoSubAdminRequired
134+
*
135+
* @param string[] $configKeys
136+
*
137+
* @return DataResponse<array, Http::STATUS_OK|Http::STATUS_BAD_REQUEST>
127138
*/
128139
public function deleteMultiplePreference(string $appId, array $configKeys): DataResponse {
129140
$userId = $this->userSession->getUser()->getUID();
@@ -157,6 +168,8 @@ public function deleteMultiplePreference(string $appId, array $configKeys): Data
157168
/**
158169
* @NoAdminRequired
159170
* @NoSubAdminRequired
171+
*
172+
* @return DataResponse<array, Http::STATUS_OK|Http::STATUS_BAD_REQUEST>
160173
*/
161174
public function deletePreference(string $appId, string $configKey): DataResponse {
162175
$userId = $this->userSession->getUser()->getUID();

0 commit comments

Comments
 (0)