Skip to content

Commit 24d5d52

Browse files
provokateurinprovokateurin
committed
provisioning_api: Add OpenAPI spec
Signed-off-by: jld3103 <jld3103yt@gmail.com>
1 parent 9bf6911 commit 24d5d52

15 files changed

Lines changed: 556 additions & 348 deletions

‎apps/provisioning_api/composer/composer/autoload_classmap.php‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,4 +20,5 @@
2020
'OCA\\Provisioning_API\\Listener\\UserDeletedListener' => $baseDir . '/../lib/Listener/UserDeletedListener.php',
2121
'OCA\\Provisioning_API\\Middleware\\Exceptions\\NotSubAdminException' => $baseDir . '/../lib/Middleware/Exceptions/NotSubAdminException.php',
2222
'OCA\\Provisioning_API\\Middleware\\ProvisioningApiMiddleware' => $baseDir . '/../lib/Middleware/ProvisioningApiMiddleware.php',
23+
'OCA\\Provisioning_API\\ResponseDefinitions' => $baseDir . '/../lib/ResponseDefinitions.php',
2324
);

‎apps/provisioning_api/composer/composer/autoload_static.php‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ class ComposerStaticInitProvisioning_API
3535
'OCA\\Provisioning_API\\Listener\\UserDeletedListener' => __DIR__ . '/..' . '/../lib/Listener/UserDeletedListener.php',
3636
'OCA\\Provisioning_API\\Middleware\\Exceptions\\NotSubAdminException' => __DIR__ . '/..' . '/../lib/Middleware/Exceptions/NotSubAdminException.php',
3737
'OCA\\Provisioning_API\\Middleware\\ProvisioningApiMiddleware' => __DIR__ . '/..' . '/../lib/Middleware/ProvisioningApiMiddleware.php',
38+
'OCA\\Provisioning_API\\ResponseDefinitions' => __DIR__ . '/..' . '/../lib/ResponseDefinitions.php',
3839
);
3940

4041
public static function getInitializer(ClassLoader $loader)

‎apps/provisioning_api/lib/Capabilities.php‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
* @copyright Copyright (c) 2021 Vincent Petry <vincent@nextcloud.com>
44
*
55
* @author Vincent Petry <vincent@nextcloud.com>
6+
* @author Kate Döen <kate.doeen@nextcloud.com>
67
*
78
* @license GNU AGPL version 3 or any later version
89
*
@@ -37,6 +38,15 @@ public function __construct(IAppManager $appManager) {
3738

3839
/**
3940
* Function an app uses to return the capabilities
41+
*
42+
* @return array{
43+
* provisioning_api: array{
44+
* version: string,
45+
* AccountPropertyScopesVersion: int,
46+
* AccountPropertyScopesFederatedEnabled: bool,
47+
* AccountPropertyScopesPublishedEnabled: bool,
48+
* },
49+
* }
4050
*/
4151
public function getCapabilities() {
4252
$federatedScopeEnabled = $this->appManager->isEnabledForUser('federation');

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

Lines changed: 10 additions & 5 deletions
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,10 @@
5253
use OCP\User\Backend\ISetDisplayNameBackend;
5354
use OCP\User\Backend\ISetPasswordBackend;
5455

56+
/**
57+
* @psalm-import-type ProvisioningApiUserDetails from ResponseDefinitions
58+
* @psalm-import-type ProvisioningApiUserDetailsQuota from ResponseDefinitions
59+
*/
5560
abstract class AUserData extends OCSController {
5661
public const SCOPE_SUFFIX = 'Scope';
5762

@@ -99,12 +104,12 @@ public function __construct(string $appName,
99104
*
100105
* @param string $userId
101106
* @param bool $includeScopes
102-
* @return array
107+
* @return ProvisioningApiUserDetails|null
103108
* @throws NotFoundException
104109
* @throws OCSException
105110
* @throws OCSNotFoundException
106111
*/
107-
protected function getUserData(string $userId, bool $includeScopes = false): array {
112+
protected function getUserData(string $userId, bool $includeScopes = false): ?array {
108113
$currentLoggedInUser = $this->userSession->getUser();
109114
assert($currentLoggedInUser !== null, 'No user logged in');
110115

@@ -123,7 +128,7 @@ protected function getUserData(string $userId, bool $includeScopes = false): arr
123128
} else {
124129
// Check they are looking up themselves
125130
if ($currentLoggedInUser->getUID() !== $targetUserObject->getUID()) {
126-
return $data;
131+
return null;
127132
}
128133
}
129134

@@ -225,7 +230,7 @@ protected function getUserData(string $userId, bool $includeScopes = false): arr
225230
* Get the groups a user is a subadmin of
226231
*
227232
* @param string $userId
228-
* @return array
233+
* @return string[]
229234
* @throws OCSException
230235
*/
231236
protected function getUserSubAdminGroupsData(string $userId): array {
@@ -247,7 +252,7 @@ protected function getUserSubAdminGroupsData(string $userId): array {
247252

248253
/**
249254
* @param string $userId
250-
* @return array
255+
* @return ProvisioningApiUserDetailsQuota
251256
* @throws OCSException
252257
*/
253258
protected function fillStorageInfo(string $userId): array {

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

Lines changed: 39 additions & 14 deletions
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,9 @@ public function __construct(string $appName,
8485
}
8586

8687
/**
87-
* @return DataResponse
88+
* Get a list of apps
89+
*
90+
* @return DataResponse<Http::STATUS_OK, array{data: string[]}, array{}>
8891
*/
8992
public function getApps(): DataResponse {
9093
return new DataResponse([
@@ -93,8 +96,13 @@ public function getApps(): DataResponse {
9396
}
9497

9598
/**
96-
* @param string $app
97-
* @return DataResponse
99+
* Get the config keys of an app
100+
*
101+
* @param string $app ID of the app
102+
* @return DataResponse<Http::STATUS_OK, array{data: string[]}, array{}>|DataResponse<Http::STATUS_FORBIDDEN, array{data: array{message: string}}, array{}>
103+
*
104+
* 200: Keys returned
105+
* 403: App is not allowed
98106
*/
99107
public function getKeys(string $app): DataResponse {
100108
try {
@@ -108,10 +116,15 @@ public function getKeys(string $app): DataResponse {
108116
}
109117

110118
/**
111-
* @param string $app
112-
* @param string $key
113-
* @param string $defaultValue
114-
* @return DataResponse
119+
* Get a the config value of an app
120+
*
121+
* @param string $app ID if the app
122+
* @param string $key Key
123+
* @param string $defaultValue Default returned value if the value is empty
124+
* @return DataResponse<Http::STATUS_OK, array{data: string}, array{}>|DataResponse<Http::STATUS_FORBIDDEN, array{data: array{message: string}}, array{}>
125+
*
126+
* 200: Value returned
127+
* 403: App is not allowed
115128
*/
116129
public function getValue(string $app, string $key, string $defaultValue = ''): DataResponse {
117130
try {
@@ -128,10 +141,16 @@ public function getValue(string $app, string $key, string $defaultValue = ''): D
128141
* @PasswordConfirmationRequired
129142
* @NoSubAdminRequired
130143
* @NoAdminRequired
131-
* @param string $app
132-
* @param string $key
133-
* @param string $value
134-
* @return DataResponse
144+
*
145+
* Update the config value of an app
146+
*
147+
* @param string $app ID of the app
148+
* @param string $key Key to update
149+
* @param string $value New value for the key
150+
* @return DataResponse<Http::STATUS_OK, array<empty>, array{}>|DataResponse<Http::STATUS_FORBIDDEN, array{data: array{message: string}}, array{}>
151+
*
152+
* 200: Value updated successfully
153+
* 403: App or key is not allowed
135154
*/
136155
public function setValue(string $app, string $key, string $value): DataResponse {
137156
$user = $this->userSession->getUser();
@@ -156,9 +175,15 @@ public function setValue(string $app, string $key, string $value): DataResponse
156175

157176
/**
158177
* @PasswordConfirmationRequired
159-
* @param string $app
160-
* @param string $key
161-
* @return DataResponse
178+
*
179+
* Delete a config key of an app
180+
*
181+
* @param string $app ID of the app
182+
* @param string $key Key to delete
183+
* @return DataResponse<Http::STATUS_OK, array<empty>, array{}>|DataResponse<Http::STATUS_FORBIDDEN, array{data: array{message: string}}, array{}>
184+
*
185+
* 200: Key deleted successfully
186+
* 403: App or key is not allowed
162187
*/
163188
public function deleteKey(string $app, string $key): DataResponse {
164189
try {

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

Lines changed: 25 additions & 8 deletions
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 ProvisioningApiAppInfo from ResponseDefinitions
44+
*/
3945
class AppsController extends OCSController {
4046
/** @var IAppManager */
4147
private $appManager;
@@ -51,8 +57,10 @@ public function __construct(
5157
}
5258

5359
/**
54-
* @param string|null $filter
55-
* @return DataResponse
60+
* Get a list of installed apps
61+
*
62+
* @param string|null $filter Filter for enabled or disabled apps
63+
* @return DataResponse<Http::STATUS_OK, array{apps: string[]}, array{}>
5664
* @throws OCSException
5765
*/
5866
public function getApps(string $filter = null): DataResponse {
@@ -61,6 +69,7 @@ public function getApps(string $filter = null): DataResponse {
6169
foreach ($apps as $app) {
6270
$list[] = $app['id'];
6371
}
72+
/** @var string[] $list */
6473
if ($filter) {
6574
switch ($filter) {
6675
case 'enabled':
@@ -80,8 +89,10 @@ public function getApps(string $filter = null): DataResponse {
8089
}
8190

8291
/**
83-
* @param string $app
84-
* @return DataResponse
92+
* Get the app info for an app
93+
*
94+
* @param string $app ID of the app
95+
* @return DataResponse<Http::STATUS_OK, ProvisioningApiAppInfo, array{}>
8596
* @throws OCSException
8697
*/
8798
public function getAppInfo(string $app): DataResponse {
@@ -95,8 +106,11 @@ public function getAppInfo(string $app): DataResponse {
95106

96107
/**
97108
* @PasswordConfirmationRequired
98-
* @param string $app
99-
* @return DataResponse
109+
*
110+
* Enable an app
111+
*
112+
* @param string $app ID of the app
113+
* @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
100114
* @throws OCSException
101115
*/
102116
public function enable(string $app): DataResponse {
@@ -110,8 +124,11 @@ public function enable(string $app): DataResponse {
110124

111125
/**
112126
* @PasswordConfirmationRequired
113-
* @param string $app
114-
* @return DataResponse
127+
*
128+
* Disable an app
129+
*
130+
* @param string $app ID of the app
131+
* @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
115132
*/
116133
public function disable(string $app): DataResponse {
117134
$this->appManager->disableApp($app);

0 commit comments

Comments
 (0)