Merge pull request #39223 from nextcloud/feature/openapi/provisioning…

…_api

provisioning_api: Add OpenAPI spec

apps/provisioning_api/composer/composer/autoload_classmap.php

@@ -20,4 +20,5 @@
     'OCA\\Provisioning_API\\Listener\\UserDeletedListener' => $baseDir . '/../lib/Listener/UserDeletedListener.php',
     'OCA\\Provisioning_API\\Middleware\\Exceptions\\NotSubAdminException' => $baseDir . '/../lib/Middleware/Exceptions/NotSubAdminException.php',
     'OCA\\Provisioning_API\\Middleware\\ProvisioningApiMiddleware' => $baseDir . '/../lib/Middleware/ProvisioningApiMiddleware.php',
+    'OCA\\Provisioning_API\\ResponseDefinitions' => $baseDir . '/../lib/ResponseDefinitions.php',
 );

apps/provisioning_api/composer/composer/autoload_static.php

@@ -35,6 +35,7 @@ class ComposerStaticInitProvisioning_API
         'OCA\\Provisioning_API\\Listener\\UserDeletedListener' => __DIR__ . '/..' . '/../lib/Listener/UserDeletedListener.php',
         'OCA\\Provisioning_API\\Middleware\\Exceptions\\NotSubAdminException' => __DIR__ . '/..' . '/../lib/Middleware/Exceptions/NotSubAdminException.php',
         'OCA\\Provisioning_API\\Middleware\\ProvisioningApiMiddleware' => __DIR__ . '/..' . '/../lib/Middleware/ProvisioningApiMiddleware.php',
+        'OCA\\Provisioning_API\\ResponseDefinitions' => __DIR__ . '/..' . '/../lib/ResponseDefinitions.php',
     );
 
     public static function getInitializer(ClassLoader $loader)

apps/provisioning_api/lib/Capabilities.php

@@ -3,6 +3,7 @@
  * @copyright Copyright (c) 2021 Vincent Petry <[email protected]>
  *
  * @author Vincent Petry <[email protected]>
+ * @author Kate Döen <[email protected]>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -37,6 +38,15 @@ public function __construct(IAppManager $appManager) {
 
 	/**
 	 * Function an app uses to return the capabilities
+	 *
+	 * @return array{
+	 *     provisioning_api: array{
+	 *         version: string,
+	 *         AccountPropertyScopesVersion: int,
+	 *         AccountPropertyScopesFederatedEnabled: bool,
+	 *         AccountPropertyScopesPublishedEnabled: bool,
+	 *     },
+	 * }
 	 */
 	public function getCapabilities() {
 		$federatedScopeEnabled = $this->appManager->isEnabledForUser('federation');

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,10 @@
 use OCP\User\Backend\ISetDisplayNameBackend;
 use OCP\User\Backend\ISetPasswordBackend;
 
+/**
+ * @psalm-import-type ProvisioningApiUserDetails from ResponseDefinitions
+ * @psalm-import-type ProvisioningApiUserDetailsQuota from ResponseDefinitions
+ */
 abstract class AUserData extends OCSController {
 	public const SCOPE_SUFFIX = 'Scope';
 
@@ -99,12 +104,12 @@ public function __construct(string $appName,
 	 *
 	 * @param string $userId
 	 * @param bool $includeScopes
-	 * @return array
+	 * @return ProvisioningApiUserDetails|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');
 
@@ -123,7 +128,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;
 			}
 		}
 
@@ -225,7 +230,7 @@ protected function getUserData(string $userId, bool $includeScopes = false): arr
 	 * Get the groups a user is a subadmin of
 	 *
 	 * @param string $userId
-	 * @return array
+	 * @return string[]
 	 * @throws OCSException
 	 */
 	protected function getUserSubAdminGroupsData(string $userId): array {
@@ -247,7 +252,7 @@ protected function getUserSubAdminGroupsData(string $userId): array {
 
 	/**
 	 * @param string $userId
-	 * @return array
+	 * @return ProvisioningApiUserDetailsQuota
 	 * @throws OCSException
 	 */
 	protected function fillStorageInfo(string $userId): array {

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,9 @@ public function __construct(string $appName,
 	}
 
 	/**
-	 * @return DataResponse
+	 * Get a list of apps
+	 *
+	 * @return DataResponse<Http::STATUS_OK, array{data: string[]}, array{}>
 	 */
 	public function getApps(): DataResponse {
 		return new DataResponse([
@@ -93,8 +96,13 @@ public function getApps(): DataResponse {
 	}
 
 	/**
-	 * @param string $app
-	 * @return DataResponse
+	 * Get the config keys of an app
+	 *
+	 * @param string $app ID of the app
+	 * @return DataResponse<Http::STATUS_OK, array{data: string[]}, array{}>|DataResponse<Http::STATUS_FORBIDDEN, array{data: array{message: string}}, array{}>
+	 *
+	 * 200: Keys returned
+	 * 403: App is not allowed
 	 */
 	public function getKeys(string $app): DataResponse {
 		try {
@@ -108,10 +116,15 @@ public function getKeys(string $app): DataResponse {
 	}
 
 	/**
-	 * @param string $app
-	 * @param string $key
-	 * @param string $defaultValue
-	 * @return DataResponse
+	 * Get a the config value of an app
+	 *
+	 * @param string $app ID of the app
+	 * @param string $key Key
+	 * @param string $defaultValue Default returned value if the value is empty
+	 * @return DataResponse<Http::STATUS_OK, array{data: string}, array{}>|DataResponse<Http::STATUS_FORBIDDEN, array{data: array{message: string}}, array{}>
+	 *
+	 * 200: Value returned
+	 * 403: App is not allowed
 	 */
 	public function getValue(string $app, string $key, string $defaultValue = ''): DataResponse {
 		try {
@@ -128,10 +141,16 @@ public function getValue(string $app, string $key, string $defaultValue = ''): D
 	 * @PasswordConfirmationRequired
 	 * @NoSubAdminRequired
 	 * @NoAdminRequired
-	 * @param string $app
-	 * @param string $key
-	 * @param string $value
-	 * @return DataResponse
+	 *
+	 * Update the config value of an app
+	 *
+	 * @param string $app ID of the app
+	 * @param string $key Key to update
+	 * @param string $value New value for the key
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>|DataResponse<Http::STATUS_FORBIDDEN, array{data: array{message: string}}, array{}>
+	 *
+	 * 200: Value updated successfully
+	 * 403: App or key is not allowed
 	 */
 	public function setValue(string $app, string $key, string $value): DataResponse {
 		$user = $this->userSession->getUser();
@@ -156,9 +175,15 @@ public function setValue(string $app, string $key, string $value): DataResponse
 
 	/**
 	 * @PasswordConfirmationRequired
-	 * @param string $app
-	 * @param string $key
-	 * @return DataResponse
+	 *
+	 * Delete a config key of an app
+	 *
+	 * @param string $app ID of the app
+	 * @param string $key Key to delete
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>|DataResponse<Http::STATUS_FORBIDDEN, array{data: array{message: string}}, array{}>
+	 *
+	 * 200: Key deleted successfully
+	 * 403: App or key is not allowed
 	 */
 	public function deleteKey(string $app, string $key): DataResponse {
 		try {

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 ProvisioningApiAppInfo from ResponseDefinitions
+ */
 class AppsController extends OCSController {
 	/** @var IAppManager */
 	private $appManager;
@@ -51,16 +57,19 @@ public function __construct(
 	}
 
 	/**
-	 * @param string|null $filter
-	 * @return DataResponse
+	 * Get a list of installed apps
+	 *
+	 * @param ?string $filter Filter for enabled or disabled apps
+	 * @return DataResponse<Http::STATUS_OK, array{apps: string[]}, array{}>
 	 * @throws OCSException
 	 */
-	public function getApps(string $filter = null): DataResponse {
+	public function getApps(?string $filter = null): DataResponse {
 		$apps = (new OC_App())->listAllApps();
 		$list = [];
 		foreach ($apps as $app) {
 			$list[] = $app['id'];
 		}
+		/** @var string[] $list */
 		if ($filter) {
 			switch ($filter) {
 				case 'enabled':
@@ -80,8 +89,10 @@ public function getApps(string $filter = null): DataResponse {
 	}
 
 	/**
-	 * @param string $app
-	 * @return DataResponse
+	 * Get the app info for an app
+	 *
+	 * @param string $app ID of the app
+	 * @return DataResponse<Http::STATUS_OK, ProvisioningApiAppInfo, array{}>
 	 * @throws OCSException
 	 */
 	public function getAppInfo(string $app): DataResponse {
@@ -95,8 +106,11 @@ public function getAppInfo(string $app): DataResponse {
 
 	/**
 	 * @PasswordConfirmationRequired
-	 * @param string $app
-	 * @return DataResponse
+	 *
+	 * Enable an app
+	 *
+	 * @param string $app ID of the app
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
 	 * @throws OCSException
 	 */
 	public function enable(string $app): DataResponse {
@@ -110,8 +124,11 @@ public function enable(string $app): DataResponse {
 
 	/**
 	 * @PasswordConfirmationRequired
-	 * @param string $app
-	 * @return DataResponse
+	 *
+	 * Disable an app
+	 *
+	 * @param string $app ID of the app
+	 * @return DataResponse<Http::STATUS_OK, array<empty>, array{}>
 	 */
 	public function disable(string $app): DataResponse {
 		$this->appManager->disableApp($app);