files_external: Add OpenAPI spec

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

diff --git a/apps/files_external/composer/composer/autoload_classmap.php b/apps/files_external/composer/composer/autoload_classmap.php
index c6037ea9ded82b0b1aa419bff0e0528eb4073a58..cf6f72c0fe2b8ce49bc050fc7aa5d284775fc216 100644 (file)
--- 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 26091fb32b3e0b9171dfa69de51e486ef75da3e4..4ba4f602c6bbc1b9707013005256bd7e23be0831 100644 (file)
--- 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 40539d0bbcaec75be25d643e1842ac9a988af2eb..ed54837a9bdafdf99072bbdde892cdff442e65f8 100644 (file)
--- 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<Http::STATUS_OK, FilesExternalMount[], array{}>
         */
        public function getUserMounts(): DataResponse {
                $entries = [];

diff --git a/apps/files_external/lib/Lib/StorageConfig.php b/apps/files_external/lib/Lib/StorageConfig.php
index 757f9d35bdbe9939010883a8b53c400d059e4623..be61d2982c0b9739fd56065d8da4e215f880c7c1 100644 (file)
--- 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 (file)
index 0000000..d26d05a
--- /dev/null
+++ b/apps/files_external/lib/ResponseDefinitions.php
@@ -0,0 +1,41 @@
+<?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\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 (file)
index 0000000..a95ab67
--- /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