From bb1e73de9737dede61ae96081719ddf2e87a9bf2 Mon Sep 17 00:00:00 2001 From: jld3103 Date: Wed, 14 Jun 2023 16:28:26 +0200 Subject: [PATCH] files_external: Add OpenAPI spec Signed-off-by: jld3103 --- .../composer/composer/autoload_classmap.php | 1 + .../composer/composer/autoload_static.php | 1 + .../lib/Controller/ApiController.php | 11 +- apps/files_external/lib/Lib/StorageConfig.php | 2 +- .../lib/ResponseDefinitions.php | 41 +++++ apps/files_external/openapi.json | 163 ++++++++++++++++++ 6 files changed, 215 insertions(+), 4 deletions(-) create mode 100644 apps/files_external/lib/ResponseDefinitions.php create mode 100644 apps/files_external/openapi.json diff --git a/apps/files_external/composer/composer/autoload_classmap.php b/apps/files_external/composer/composer/autoload_classmap.php index c6037ea9ded..cf6f72c0fe2 100644 --- a/apps/files_external/composer/composer/autoload_classmap.php +++ b/apps/files_external/composer/composer/autoload_classmap.php @@ -105,6 +105,7 @@ return array( 'OCA\\Files_External\\Migration\\Version22000Date20210216084416' => $baseDir . '/../lib/Migration/Version22000Date20210216084416.php', 'OCA\\Files_External\\MountConfig' => $baseDir . '/../lib/MountConfig.php', 'OCA\\Files_External\\NotFoundException' => $baseDir . '/../lib/NotFoundException.php', + 'OCA\\Files_External\\ResponseDefinitions' => $baseDir . '/../lib/ResponseDefinitions.php', 'OCA\\Files_External\\Service\\BackendService' => $baseDir . '/../lib/Service/BackendService.php', 'OCA\\Files_External\\Service\\DBConfigService' => $baseDir . '/../lib/Service/DBConfigService.php', 'OCA\\Files_External\\Service\\GlobalStoragesService' => $baseDir . '/../lib/Service/GlobalStoragesService.php', diff --git a/apps/files_external/composer/composer/autoload_static.php b/apps/files_external/composer/composer/autoload_static.php index 26091fb32b3..4ba4f602c6b 100644 --- a/apps/files_external/composer/composer/autoload_static.php +++ b/apps/files_external/composer/composer/autoload_static.php @@ -120,6 +120,7 @@ class ComposerStaticInitFiles_External 'OCA\\Files_External\\Migration\\Version22000Date20210216084416' => __DIR__ . '/..' . '/../lib/Migration/Version22000Date20210216084416.php', 'OCA\\Files_External\\MountConfig' => __DIR__ . '/..' . '/../lib/MountConfig.php', 'OCA\\Files_External\\NotFoundException' => __DIR__ . '/..' . '/../lib/NotFoundException.php', + 'OCA\\Files_External\\ResponseDefinitions' => __DIR__ . '/..' . '/../lib/ResponseDefinitions.php', 'OCA\\Files_External\\Service\\BackendService' => __DIR__ . '/..' . '/../lib/Service/BackendService.php', 'OCA\\Files_External\\Service\\DBConfigService' => __DIR__ . '/..' . '/../lib/Service/DBConfigService.php', 'OCA\\Files_External\\Service\\GlobalStoragesService' => __DIR__ . '/..' . '/../lib/Service/GlobalStoragesService.php', diff --git a/apps/files_external/lib/Controller/ApiController.php b/apps/files_external/lib/Controller/ApiController.php index 40539d0bbca..ed54837a9bd 100644 --- a/apps/files_external/lib/Controller/ApiController.php +++ b/apps/files_external/lib/Controller/ApiController.php @@ -30,13 +30,18 @@ declare(strict_types=1); namespace OCA\Files_External\Controller; use OCA\Files_External\Lib\StorageConfig; +use OCA\Files_External\ResponseDefinitions; use OCA\Files_External\Service\UserGlobalStoragesService; use OCA\Files_External\Service\UserStoragesService; +use OCP\AppFramework\Http; use OCP\AppFramework\Http\DataResponse; use OCP\AppFramework\OCSController; use OCP\IRequest; use OCP\IUserSession; +/** + * @psalm-import-type FilesExternalMount from ResponseDefinitions + */ class ApiController extends OCSController { /** @var IUserSession */ @@ -66,7 +71,7 @@ class ApiController extends OCSController { * @param string $mountPoint mount point name, relative to the data dir * @param StorageConfig $mountConfig mount config to format * - * @return array entry + * @return FilesExternalMount */ private function formatMount(string $mountPoint, StorageConfig $mountConfig): array { // split path from mount point @@ -99,9 +104,9 @@ class ApiController extends OCSController { /** * @NoAdminRequired * - * Returns the mount points visible for this user. + * Get the mount points visible for this user * - * @return DataResponse share information + * @return DataResponse */ public function getUserMounts(): DataResponse { $entries = []; diff --git a/apps/files_external/lib/Lib/StorageConfig.php b/apps/files_external/lib/Lib/StorageConfig.php index 757f9d35bdb..be61d2982c0 100644 --- a/apps/files_external/lib/Lib/StorageConfig.php +++ b/apps/files_external/lib/Lib/StorageConfig.php @@ -136,7 +136,7 @@ class StorageConfig implements \JsonSerializable { /** * Returns the configuration id * - * @retun int + * @return int */ public function getId() { return $this->id; diff --git a/apps/files_external/lib/ResponseDefinitions.php b/apps/files_external/lib/ResponseDefinitions.php new file mode 100644 index 00000000000..d26d05a36f4 --- /dev/null +++ b/apps/files_external/lib/ResponseDefinitions.php @@ -0,0 +1,41 @@ + + * + * @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\Files_External; + +/** + * @psalm-type FilesExternalMount = array{ + * name: string, + * path: string, + * type: 'dir', + * backend: string, + * scope: 'system'|'personal', + * permissions: int, + * id: int, + * class: string, + * } + */ +class ResponseDefinitions { +} diff --git a/apps/files_external/openapi.json b/apps/files_external/openapi.json new file mode 100644 index 00000000000..a95ab67697a --- /dev/null +++ b/apps/files_external/openapi.json @@ -0,0 +1,163 @@ +{ + "openapi": "3.0.3", + "info": { + "title": "files_external", + "version": "0.0.1", + "description": "Adds basic external storage support", + "license": { + "name": "agpl" + } + }, + "components": { + "securitySchemes": { + "basic_auth": { + "type": "http", + "scheme": "basic" + }, + "bearer_auth": { + "type": "http", + "scheme": "bearer" + } + }, + "schemas": { + "Mount": { + "type": "object", + "required": [ + "name", + "path", + "type", + "backend", + "scope", + "permissions", + "id", + "class" + ], + "properties": { + "name": { + "type": "string" + }, + "path": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "dir" + ] + }, + "backend": { + "type": "string" + }, + "scope": { + "type": "string", + "enum": [ + "system", + "personal" + ] + }, + "permissions": { + "type": "integer", + "format": "int64" + }, + "id": { + "type": "integer", + "format": "int64" + }, + "class": { + "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/files_external/api/v1/mounts": { + "get": { + "operationId": "api-get-user-mounts", + "summary": "Get the mount points visible for this user", + "tags": [ + "api" + ], + "security": [ + { + "bearer_auth": [] + }, + { + "basic_auth": [] + } + ], + "parameters": [ + { + "name": "OCS-APIRequest", + "in": "header", + "required": true, + "schema": { + "type": "string", + "default": "true" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "ocs" + ], + "properties": { + "ocs": { + "type": "object", + "required": [ + "meta", + "data" + ], + "properties": { + "meta": { + "$ref": "#/components/schemas/OCSMeta" + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Mount" + } + } + } + } + } + } + } + } + } + } + } + } + }, + "tags": [] +} \ No newline at end of file -- 2.39.5