provisioning_api: Add OpenAPI spec

Signed-off-by: jld3103 <[email protected]>
nextcloud · Feb 19, 2023 · 59f7f8c · 59f7f8c
1 parent 42ce50c
commit 59f7f8c
Show file tree

Hide file tree

Showing 8 changed files with 3,685 additions and 51 deletions.
diff --git a/apps/provisioning_api/lib/Controller/AUserData.php b/apps/provisioning_api/lib/Controller/AUserData.php
@@ -36,6 +36,7 @@
 use OC\User\Backend;
 use OC\User\NoUserException;
 use OC_Helper;
+use OCA\Provisioning_API\ResponseDefinitions;
 use OCP\Accounts\IAccountManager;
 use OCP\Accounts\PropertyDoesNotExistException;
 use OCP\AppFramework\Http;
@@ -52,6 +53,9 @@
 use OCP\User\Backend\ISetDisplayNameBackend;
 use OCP\User\Backend\ISetPasswordBackend;
 
+/**
+ * @psalm-import-type UserDetails from ResponseDefinitions
+ */
 abstract class AUserData extends OCSController {
 	public const SCOPE_SUFFIX = 'Scope';
 
@@ -98,12 +102,12 @@ public function __construct(string $appName,
 	 *
 	 * @param string $userId
 	 * @param bool $includeScopes
-	 * @return array
+	 * @return UserDetails|null
 	 * @throws NotFoundException
 	 * @throws OCSException
 	 * @throws OCSNotFoundException
 	 */
-	protected function getUserData(string $userId, bool $includeScopes = false): array {
+	protected function getUserData(string $userId, bool $includeScopes = false): ?array {
 		$currentLoggedInUser = $this->userSession->getUser();
 		assert($currentLoggedInUser !== null, 'No user logged in');
 
@@ -122,7 +126,7 @@ protected function getUserData(string $userId, bool $includeScopes = false): arr
 		} else {
 			// Check they are looking up themselves
 			if ($currentLoggedInUser->getUID() !== $targetUserObject->getUID()) {
-				return $data;
+				return null;
 			}
 		}
 

diff --git a/apps/provisioning_api/lib/Controller/AppConfigController.php b/apps/provisioning_api/lib/Controller/AppConfigController.php
@@ -7,6 +7,7 @@
  *
  * @author Joas Schilling <[email protected]>
  * @author Roeland Jago Douma <[email protected]>
+ * @author Kate Döen <[email protected]>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -84,7 +85,7 @@ public function __construct(string $appName,
 	}
 
 	/**
-	 * @return DataResponse
+	 * @return DataResponse<array{data: string[]}, Http::STATUS_OK>
 	 */
 	public function getApps(): DataResponse {
 		return new DataResponse([
@@ -94,7 +95,7 @@ public function getApps(): DataResponse {
 
 	/**
 	 * @param string $app
-	 * @return DataResponse
+	 * @return DataResponse<array{data: string[]}, Http::STATUS_OK>|DataResponse<array{data: array{message: string}}, Http::STATUS_FORBIDDEN>
 	 */
 	public function getKeys(string $app): DataResponse {
 		try {
@@ -111,7 +112,7 @@ public function getKeys(string $app): DataResponse {
 	 * @param string $app
 	 * @param string $key
 	 * @param string $defaultValue
-	 * @return DataResponse
+	 * @return DataResponse<array{data: string}, Http::STATUS_OK>|DataResponse<array{data: array{message: string}}, Http::STATUS_FORBIDDEN>
 	 */
 	public function getValue(string $app, string $key, string $defaultValue = ''): DataResponse {
 		try {
@@ -131,7 +132,7 @@ public function getValue(string $app, string $key, string $defaultValue = ''): D
 	 * @param string $app
 	 * @param string $key
 	 * @param string $value
-	 * @return DataResponse
+	 * @return DataResponse<array, Http::STATUS_OK>|DataResponse<array{data: array{message: string}}, Http::STATUS_FORBIDDEN>
 	 */
 	public function setValue(string $app, string $key, string $value): DataResponse {
 		$user = $this->userSession->getUser();
@@ -158,7 +159,7 @@ public function setValue(string $app, string $key, string $value): DataResponse
 	 * @PasswordConfirmationRequired
 	 * @param string $app
 	 * @param string $key
-	 * @return DataResponse
+	 * @return DataResponse<array, Http::STATUS_OK>|DataResponse<array{data: array{message: string}}, Http::STATUS_FORBIDDEN>
 	 */
 	public function deleteKey(string $app, string $key): DataResponse {
 		try {

diff --git a/apps/provisioning_api/lib/Controller/AppsController.php b/apps/provisioning_api/lib/Controller/AppsController.php
@@ -10,6 +10,7 @@
  * @author Lukas Reschke <[email protected]>
  * @author Roeland Jago Douma <[email protected]>
  * @author Tom Needham <[email protected]>
+ * @author Kate Döen <[email protected]>
  *
  * @license AGPL-3.0
  *
@@ -29,13 +30,18 @@
 namespace OCA\Provisioning_API\Controller;
 
 use OC_App;
+use OCA\Provisioning_API\ResponseDefinitions;
 use OCP\App\AppPathNotFoundException;
 use OCP\App\IAppManager;
+use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCS\OCSException;
 use OCP\AppFramework\OCSController;
 use OCP\IRequest;
 
+/**
+ * @psalm-import-type AppInfo from ResponseDefinitions
+ */
 class AppsController extends OCSController {
 	/** @var IAppManager */
 	private $appManager;
@@ -52,11 +58,12 @@ public function __construct(
 
 	/**
 	 * @param string|null $filter
-	 * @return DataResponse
+	 * @return DataResponse<array{apps: string[]}, Http::STATUS_OK>
 	 * @throws OCSException
 	 */
 	public function getApps(string $filter = null): DataResponse {
 		$apps = (new OC_App())->listAllApps();
+		/** @var string[] $list */
 		$list = [];
 		foreach ($apps as $app) {
 			$list[] = $app['id'];
@@ -81,7 +88,7 @@ public function getApps(string $filter = null): DataResponse {
 
 	/**
 	 * @param string $app
-	 * @return DataResponse
+	 * @return DataResponse<AppInfo, Http::STATUS_OK>
 	 * @throws OCSException
 	 */
 	public function getAppInfo(string $app): DataResponse {
@@ -96,7 +103,7 @@ public function getAppInfo(string $app): DataResponse {
 	/**
 	 * @PasswordConfirmationRequired
 	 * @param string $app
-	 * @return DataResponse
+	 * @return DataResponse<array, Http::STATUS_OK>
 	 * @throws OCSException
 	 */
 	public function enable(string $app): DataResponse {
@@ -111,7 +118,7 @@ public function enable(string $app): DataResponse {
 	/**
 	 * @PasswordConfirmationRequired
 	 * @param string $app
-	 * @return DataResponse
+	 * @return DataResponse<array, Http::STATUS_OK>
 	 */
 	public function disable(string $app): DataResponse {
 		$this->appManager->disableApp($app);

diff --git a/apps/provisioning_api/lib/Controller/GroupsController.php b/apps/provisioning_api/lib/Controller/GroupsController.php
@@ -14,6 +14,7 @@
  * @author Robin Appelman <[email protected]>
  * @author Roeland Jago Douma <[email protected]>
  * @author Tom Needham <[email protected]>
+ * @author Kate Döen <[email protected]>
  *
  * @license AGPL-3.0
  *
@@ -32,7 +33,9 @@
  */
 namespace OCA\Provisioning_API\Controller;
 
+use OCA\Provisioning_API\ResponseDefinitions;
 use OCP\Accounts\IAccountManager;
+use OCP\AppFramework\Http;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\AppFramework\OCS\OCSException;
 use OCP\AppFramework\OCS\OCSForbiddenException;
@@ -48,6 +51,10 @@
 use OCP\L10N\IFactory;
 use Psr\Log\LoggerInterface;
 
+/**
+ * @psalm-import-type GroupDetails from ResponseDefinitions
+ * @psalm-import-type UserDetails from ResponseDefinitions
+ */
 class GroupsController extends AUserData {
 
 	/** @var LoggerInterface */
@@ -83,7 +90,7 @@ public function __construct(string $appName,
 	 * @param string $search
 	 * @param int $limit
 	 * @param int $offset
-	 * @return DataResponse
+	 * @return DataResponse<array{groups: string[]}, Http::STATUS_OK>
 	 */
 	public function getGroups(string $search = '', int $limit = null, int $offset = 0): DataResponse {
 		$groups = $this->groupManager->search($search, $limit, $offset);
@@ -104,7 +111,7 @@ public function getGroups(string $search = '', int $limit = null, int $offset =
 	 * @param string $search
 	 * @param int $limit
 	 * @param int $offset
-	 * @return DataResponse
+	 * @return DataResponse<array{groups: GroupDetails[]}, Http::STATUS_OK>
 	 */
 	public function getGroupsDetails(string $search = '', int $limit = null, int $offset = 0): DataResponse {
 		$groups = $this->groupManager->search($search, $limit, $offset);
@@ -127,7 +134,7 @@ public function getGroupsDetails(string $search = '', int $limit = null, int $of
 	 * @NoAdminRequired
 	 *
 	 * @param string $groupId
-	 * @return DataResponse
+	 * @return DataResponse<array{users: string[]}, Http::STATUS_OK>
 	 * @throws OCSException
 	 *
 	 * @deprecated 14 Use getGroupUsers
@@ -142,8 +149,10 @@ public function getGroup(string $groupId): DataResponse {
 	 * @NoAdminRequired
 	 *
 	 * @param string $groupId
-	 * @return DataResponse
+	 * @return DataResponse<array{users: string[]}, Http::STATUS_OK>
 	 * @throws OCSException
+	 * @throws OCSNotFoundException
+	 * @throws OCSForbiddenException
 	 */
 	public function getGroupUsers(string $groupId): DataResponse {
 		$groupId = urldecode($groupId);
@@ -167,6 +176,7 @@ public function getGroupUsers(string $groupId): DataResponse {
 				/** @var IUser $user */
 				return $user->getUID();
 			}, $users);
+			/** @var string[] $users */
 			$users = array_values($users);
 			return new DataResponse(['users' => $users]);
 		}
@@ -183,7 +193,8 @@ public function getGroupUsers(string $groupId): DataResponse {
 	 * @param string $search
 	 * @param int $limit
 	 * @param int $offset
-	 * @return DataResponse
+	 *
+	 * @return DataResponse<array{users: array<string, UserDetails|array{id: string}>}, Http::STATUS_OK>
 	 * @throws OCSException
 	 */
 	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 $
 					$userId = (string)$user->getUID();
 					$userData = $this->getUserData($userId);
 					// Do not insert empty entry
-					if (!empty($userData)) {
+					if ($userData != null) {
 						$usersDetails[$userId] = $userData;
 					} else {
 						// Logged user does not have permissions to see this user
@@ -234,7 +245,7 @@ public function getGroupUsersDetails(string $groupId, string $search = '', int $
 	 *
 	 * @param string $groupid
 	 * @param string $displayname
-	 * @return DataResponse
+	 * @return DataResponse<array, Http::STATUS_OK>
 	 * @throws OCSException
 	 */
 	public function addGroup(string $groupid, string $displayname = ''): DataResponse {
@@ -263,7 +274,7 @@ public function addGroup(string $groupid, string $displayname = ''): DataRespons
 	 * @param string $groupId
 	 * @param string $key
 	 * @param string $value
-	 * @return DataResponse
+	 * @return DataResponse<array, Http::STATUS_OK>
 	 * @throws OCSException
 	 */
 	public function updateGroup(string $groupId, string $key, string $value): DataResponse {
@@ -285,7 +296,7 @@ public function updateGroup(string $groupId, string $key, string $value): DataRe
 	 * @PasswordConfirmationRequired
 	 *
 	 * @param string $groupId
-	 * @return DataResponse
+	 * @return DataResponse<array, Http::STATUS_OK>
 	 * @throws OCSException
 	 */
 	public function deleteGroup(string $groupId): DataResponse {
@@ -304,7 +315,7 @@ public function deleteGroup(string $groupId): DataResponse {
 
 	/**
 	 * @param string $groupId
-	 * @return DataResponse
+	 * @return DataResponse<string[], Http::STATUS_OK>
 	 * @throws OCSException
 	 */
 	public function getSubAdminsOfGroup(string $groupId): DataResponse {
@@ -317,6 +328,7 @@ public function getSubAdminsOfGroup(string $groupId): DataResponse {
 		/** @var IUser[] $subadmins */
 		$subadmins = $this->groupManager->getSubAdmin()->getGroupsSubAdmins($targetGroup);
 		// New class returns IUser[] so convert back
+		/** @var string[] $uids */
 		$uids = [];
 		foreach ($subadmins as $user) {
 			$uids[] = $user->getUID();

diff --git a/apps/provisioning_api/lib/Controller/PreferencesController.php b/apps/provisioning_api/lib/Controller/PreferencesController.php
@@ -6,6 +6,7 @@
  * @copyright Copyright (c) 2022 Joas Schilling <[email protected]>
  *
  * @author Joas Schilling <[email protected]>
+ * @author Kate Döen <[email protected]>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -58,6 +59,10 @@ public function __construct(
 	/**
 	 * @NoAdminRequired
 	 * @NoSubAdminRequired
+	 *
+	 * @param array<string, string> $configs
+	 *
+	 * @return DataResponse<array, Http::STATUS_OK|Http::STATUS_BAD_REQUEST>
 	 */
 	public function setMultiplePreferences(string $appId, array $configs): DataResponse {
 		$userId = $this->userSession->getUser()->getUID();
@@ -93,6 +98,8 @@ public function setMultiplePreferences(string $appId, array $configs): DataRespo
 	/**
 	 * @NoAdminRequired
 	 * @NoSubAdminRequired
+	 *
+	 * @return DataResponse<array, Http::STATUS_OK|Http::STATUS_BAD_REQUEST>
 	 */
 	public function setPreference(string $appId, string $configKey, string $configValue): DataResponse {
 		$userId = $this->userSession->getUser()->getUID();
@@ -124,6 +131,10 @@ public function setPreference(string $appId, string $configKey, string $configVa
 	/**
 	 * @NoAdminRequired
 	 * @NoSubAdminRequired
+	 *
+	 * @param string[] $configKeys
+	 *
+	 * @return DataResponse<array, Http::STATUS_OK|Http::STATUS_BAD_REQUEST>
 	 */
 	public function deleteMultiplePreference(string $appId, array $configKeys): DataResponse {
 		$userId = $this->userSession->getUser()->getUID();
@@ -157,6 +168,8 @@ public function deleteMultiplePreference(string $appId, array $configKeys): Data
 	/**
 	 * @NoAdminRequired
 	 * @NoSubAdminRequired
+	 *
+	 * @return DataResponse<array, Http::STATUS_OK|Http::STATUS_BAD_REQUEST>
 	 */
 	public function deletePreference(string $appId, string $configKey): DataResponse {
 		$userId = $this->userSession->getUser()->getUID();