files_external: Add OpenAPI spec

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

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',

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',

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 = [];

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;

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 {
+}

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": []
+}