provisioning_api: Add OpenAPI spec

Signed-off-by: jld3103 <jld3103yt@gmail.com>

1 files changed, 26 insertions, 9 deletions

diff --git a/apps/provisioning_api/lib/Controller/AppsController.php b/apps/provisioning_api/lib/Controller/AppsController.php
index fa0f2597e7f..7f84bdeb9db 100644
--- a/apps/provisioning_api/lib/Controller/AppsController.php
+++ b/apps/provisioning_api/lib/Controller/AppsController.php
@@ -10,6 +10,7 @@ declare(strict_types=1);
  * @author Lukas Reschke <lukas@statuscode.ch>
  * @author Roeland Jago Douma <roeland@famdouma.nl>
  * @author Tom Needham <tom@owncloud.com>
+ * @author Kate Döen <kate.doeen@nextcloud.com>
  *
  * @license AGPL-3.0
  *
@@ -29,13 +30,18 @@ declare(strict_types=1);
 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 @@ class AppsController extends OCSController {
 	}
 
 	/**
-	 * @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 @@ class AppsController extends OCSController {
 	}
 
 	/**
-	 * @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 @@ class AppsController extends OCSController {
 
 	/**
 	 * @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 @@ class AppsController extends OCSController {
 
 	/**
 	 * @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);