updatenotification: Add OpenAPI spec

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

5 files changed, 261 insertions, 4 deletions

diff --git a/apps/updatenotification/composer/composer/autoload_classmap.php b/apps/updatenotification/composer/composer/autoload_classmap.php
index 9d31d6c36db..61cfbe2ec76 100644
--- a/apps/updatenotification/composer/composer/autoload_classmap.php
+++ b/apps/updatenotification/composer/composer/autoload_classmap.php
@@ -14,6 +14,7 @@ return array(
     'OCA\\UpdateNotification\\Notification\\BackgroundJob' => $baseDir . '/../lib/Notification/BackgroundJob.php',
     'OCA\\UpdateNotification\\Notification\\Notifier' => $baseDir . '/../lib/Notification/Notifier.php',
     'OCA\\UpdateNotification\\ResetTokenBackgroundJob' => $baseDir . '/../lib/ResetTokenBackgroundJob.php',
+    'OCA\\UpdateNotification\\ResponseDefinitions' => $baseDir . '/../lib/ResponseDefinitions.php',
     'OCA\\UpdateNotification\\Settings\\Admin' => $baseDir . '/../lib/Settings/Admin.php',
     'OCA\\UpdateNotification\\UpdateChecker' => $baseDir . '/../lib/UpdateChecker.php',
 );
diff --git a/apps/updatenotification/composer/composer/autoload_static.php b/apps/updatenotification/composer/composer/autoload_static.php
index 98d550b5f9b..d83927001ad 100644
--- a/apps/updatenotification/composer/composer/autoload_static.php
+++ b/apps/updatenotification/composer/composer/autoload_static.php
@@ -29,6 +29,7 @@ class ComposerStaticInitUpdateNotification
         'OCA\\UpdateNotification\\Notification\\BackgroundJob' => __DIR__ . '/..' . '/../lib/Notification/BackgroundJob.php',
         'OCA\\UpdateNotification\\Notification\\Notifier' => __DIR__ . '/..' . '/../lib/Notification/Notifier.php',
         'OCA\\UpdateNotification\\ResetTokenBackgroundJob' => __DIR__ . '/..' . '/../lib/ResetTokenBackgroundJob.php',
+        'OCA\\UpdateNotification\\ResponseDefinitions' => __DIR__ . '/..' . '/../lib/ResponseDefinitions.php',
         'OCA\\UpdateNotification\\Settings\\Admin' => __DIR__ . '/..' . '/../lib/Settings/Admin.php',
         'OCA\\UpdateNotification\\UpdateChecker' => __DIR__ . '/..' . '/../lib/UpdateChecker.php',
     );
diff --git a/apps/updatenotification/lib/Controller/APIController.php b/apps/updatenotification/lib/Controller/APIController.php
index 26657eb66f0..8833f6e772e 100644
--- a/apps/updatenotification/lib/Controller/APIController.php
+++ b/apps/updatenotification/lib/Controller/APIController.php
@@ -27,6 +27,7 @@ declare(strict_types=1);
 namespace OCA\UpdateNotification\Controller;
 
 use OC\App\AppStore\Fetcher\AppFetcher;
+use OCA\UpdateNotification\ResponseDefinitions;
 use OCP\App\AppPathNotFoundException;
 use OCP\App\IAppManager;
 use OCP\AppFramework\Http;
@@ -37,6 +38,9 @@ use OCP\IRequest;
 use OCP\IUserSession;
 use OCP\L10N\IFactory;
 
+/**
+ * @psalm-import-type UpdatenotificationApp from ResponseDefinitions
+ */
 class APIController extends OCSController {
 
 	/** @var IConfig */
@@ -86,8 +90,14 @@ class APIController extends OCSController {
 	}
 
 	/**
-	 * @param string $newVersion
-	 * @return DataResponse
+	 * List available updates for apps
+	 *
+	 * @param string $newVersion Server version to check updates for
+	 *
+	 * @return DataResponse<Http::STATUS_OK, array{missing: UpdatenotificationApp[], available: UpdatenotificationApp[]}, array{}>|DataResponse<Http::STATUS_NOT_FOUND, array{appstore_disabled: bool, already_on_latest?: bool}, array{}>
+	 *
+	 * 200: Apps returned
+	 * 404: New versions not found
 	 */
 	public function getAppList(string $newVersion): DataResponse {
 		if (!$this->config->getSystemValue('appstoreenabled', true)) {
@@ -157,13 +167,15 @@ class APIController extends OCSController {
 	 * Get translated app name
 	 *
 	 * @param string $appId
-	 * @return string[]
+	 * @return UpdatenotificationApp
 	 */
 	protected function getAppDetails(string $appId): array {
 		$app = $this->appManager->getAppInfo($appId, false, $this->language);
+		/** @var ?string $name */
+		$name = $app['name'];
 		return [
 			'appId' => $appId,
-			'appName' => $app['name'] ?? $appId,
+			'appName' => $name ?? $appId,
 		];
 	}
 }
diff --git a/apps/updatenotification/lib/ResponseDefinitions.php b/apps/updatenotification/lib/ResponseDefinitions.php
new file mode 100644
index 00000000000..01b16b81dd0
--- /dev/null
+++ b/apps/updatenotification/lib/ResponseDefinitions.php
@@ -0,0 +1,35 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2023 Kate Döen <kate.doeen@nextcloud.com>
+ *
+ * @author Kate Döen <kate.doeen@nextcloud.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCA\UpdateNotification;
+
+/**
+ * @psalm-type UpdatenotificationApp = array{
+ *     appId: string,
+ *     appName: string,
+ * }
+ */
+class ResponseDefinitions {
+}
diff --git a/apps/updatenotification/openapi.json b/apps/updatenotification/openapi.json
new file mode 100644
index 00000000000..7897a25373d
--- /dev/null
+++ b/apps/updatenotification/openapi.json
@@ -0,0 +1,208 @@
+{
+    "openapi": "3.0.3",
+    "info": {
+        "title": "updatenotification",
+        "version": "0.0.1",
+        "description": "Displays update notifications for Nextcloud and provides the SSO for the updater.",
+        "license": {
+            "name": "agpl"
+        }
+    },
+    "components": {
+        "securitySchemes": {
+            "basic_auth": {
+                "type": "http",
+                "scheme": "basic"
+            },
+            "bearer_auth": {
+                "type": "http",
+                "scheme": "bearer"
+            }
+        },
+        "schemas": {
+            "App": {
+                "type": "object",
+                "required": [
+                    "appId",
+                    "appName"
+                ],
+                "properties": {
+                    "appId": {
+                        "type": "string"
+                    },
+                    "appName": {
+                        "type": "string"
+                    }
+                }
+            },
+            "OCSMeta": {
+                "type": "object",
+                "required": [
+                    "status",
+                    "statuscode"
+                ],
+                "properties": {
+                    "status": {
+                        "type": "string"
+                    },
+                    "statuscode": {
+                        "type": "integer"
+                    },
+                    "message": {
+                        "type": "string"
+                    },
+                    "totalitems": {
+                        "type": "string"
+                    },
+                    "itemsperpage": {
+                        "type": "string"
+                    }
+                }
+            }
+        }
+    },
+    "paths": {
+        "/ocs/v2.php/apps/updatenotification/api/{apiVersion}/applist/{newVersion}": {
+            "get": {
+                "operationId": "api-get-app-list",
+                "summary": "List available updates for apps",
+                "description": "This endpoint requires admin access",
+                "tags": [
+                    "api"
+                ],
+                "security": [
+                    {
+                        "bearer_auth": []
+                    },
+                    {
+                        "basic_auth": []
+                    }
+                ],
+                "parameters": [
+                    {
+                        "name": "apiVersion",
+                        "in": "path",
+                        "required": true,
+                        "schema": {
+                            "type": "string",
+                            "enum": [
+                                "v1"
+                            ],
+                            "default": "v1"
+                        }
+                    },
+                    {
+                        "name": "newVersion",
+                        "in": "path",
+                        "description": "Server version to check updates for",
+                        "required": true,
+                        "schema": {
+                            "type": "string"
+                        }
+                    },
+                    {
+                        "name": "OCS-APIRequest",
+                        "in": "header",
+                        "required": true,
+                        "schema": {
+                            "type": "string",
+                            "default": "true"
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Apps returned",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "required": [
+                                        "ocs"
+                                    ],
+                                    "properties": {
+                                        "ocs": {
+                                            "type": "object",
+                                            "required": [
+                                                "meta",
+                                                "data"
+                                            ],
+                                            "properties": {
+                                                "meta": {
+                                                    "$ref": "#/components/schemas/OCSMeta"
+                                                },
+                                                "data": {
+                                                    "type": "object",
+                                                    "required": [
+                                                        "missing",
+                                                        "available"
+                                                    ],
+                                                    "properties": {
+                                                        "missing": {
+                                                            "type": "array",
+                                                            "items": {
+                                                                "$ref": "#/components/schemas/App"
+                                                            }
+                                                        },
+                                                        "available": {
+                                                            "type": "array",
+                                                            "items": {
+                                                                "$ref": "#/components/schemas/App"
+                                                            }
+                                                        }
+                                                    }
+                                                }
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "New versions not found",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "required": [
+                                        "ocs"
+                                    ],
+                                    "properties": {
+                                        "ocs": {
+                                            "type": "object",
+                                            "required": [
+                                                "meta",
+                                                "data"
+                                            ],
+                                            "properties": {
+                                                "meta": {
+                                                    "$ref": "#/components/schemas/OCSMeta"
+                                                },
+                                                "data": {
+                                                    "type": "object",
+                                                    "required": [
+                                                        "appstore_disabled"
+                                                    ],
+                                                    "properties": {
+                                                        "appstore_disabled": {
+                                                            "type": "boolean"
+                                                        },
+                                                        "already_on_latest": {
+                                                            "type": "boolean"
+                                                        }
+                                                    }
+                                                }
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "tags": []
+}
\ No newline at end of file