From 0c2bff63e48e87f2411a503a168ede98f42a25ad Mon Sep 17 00:00:00 2001 From: jld3103 Date: Wed, 14 Jun 2023 16:52:26 +0200 Subject: [PATCH] updatenotification: Add OpenAPI spec Signed-off-by: jld3103 --- .../composer/composer/autoload_classmap.php | 1 + .../composer/composer/autoload_static.php | 1 + .../lib/Controller/APIController.php | 20 +- .../lib/ResponseDefinitions.php | 35 +++ apps/updatenotification/openapi.json | 208 ++++++++++++++++++ 5 files changed, 261 insertions(+), 4 deletions(-) create mode 100644 apps/updatenotification/lib/ResponseDefinitions.php create mode 100644 apps/updatenotification/openapi.json diff --git a/apps/updatenotification/composer/composer/autoload_classmap.php b/apps/updatenotification/composer/composer/autoload_classmap.php index 9d31d6c36db66..61cfbe2ec764a 100644 --- a/apps/updatenotification/composer/composer/autoload_classmap.php +++ b/apps/updatenotification/composer/composer/autoload_classmap.php @@ -14,6 +14,7 @@ '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 98d550b5f9b5c..d83927001adc3 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 26657eb66f0b8..8833f6e772e0c 100644 --- a/apps/updatenotification/lib/Controller/APIController.php +++ b/apps/updatenotification/lib/Controller/APIController.php @@ -27,6 +27,7 @@ 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\IUserSession; use OCP\L10N\IFactory; +/** + * @psalm-import-type UpdatenotificationApp from ResponseDefinitions + */ class APIController extends OCSController { /** @var IConfig */ @@ -86,8 +90,14 @@ public function __construct(string $appName, } /** - * @param string $newVersion - * @return DataResponse + * List available updates for apps + * + * @param string $newVersion Server version to check updates for + * + * @return DataResponse|DataResponse + * + * 200: Apps returned + * 404: New versions not found */ public function getAppList(string $newVersion): DataResponse { if (!$this->config->getSystemValue('appstoreenabled', true)) { @@ -157,13 +167,15 @@ public function getAppList(string $newVersion): DataResponse { * 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 0000000000000..01b16b81dd053 --- /dev/null +++ b/apps/updatenotification/lib/ResponseDefinitions.php @@ -0,0 +1,35 @@ + + * + * @author Kate Döen + * + * @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 . + * + */ + +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 0000000000000..7897a25373d9c --- /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