feat(files): Update openapi spec

Signed-off-by: Christopher Ng <[email protected]>
nextcloud · Aug 1, 2024 · 012e268 · 012e268
1 parent 8f27cd6
commit 012e268
Show file tree

Hide file tree

Showing 3 changed files with 104 additions and 1 deletion.
diff --git a/apps/files/lib/Controller/ApiController.php b/apps/files/lib/Controller/ApiController.php
@@ -11,6 +11,7 @@
 use OC\Files\Node\Node;
 use OC\Files\Search\SearchComparison;
 use OC\Files\Search\SearchQuery;
+use OCA\Files\ResponseDefinitions;
 use OCA\Files\Service\TagService;
 use OCA\Files\Service\UserConfig;
 use OCA\Files\Service\ViewConfig;
@@ -46,6 +47,8 @@
 use Throwable;
 
 /**
+ * @psalm-import-type FilesFolderTree from ResponseDefinitions
+ *
  * @package OCA\Files\Controller
  */
 class ApiController extends Controller {
@@ -265,7 +268,12 @@ private function getTree(array $folders): array {
 	}
 
 	/**
-	 * Returns a folder tree for the user.
+	 * Returns the folder tree of the user
+	 *
+	 * @return JSONResponse<Http::STATUS_OK, FilesFolderTree, array{}>|JSONResponse<Http::STATUS_UNAUTHORIZED, array{message: string}, array{}>
+	 *
+	 * 200: Folder tree returned successfully
+	 * 401: Unauthorized
 	 */
 	#[NoAdminRequired]
 	#[ApiRoute(verb: 'GET', url: '/api/v1/folder-tree')]

diff --git a/apps/files/lib/ResponseDefinitions.php b/apps/files/lib/ResponseDefinitions.php
@@ -38,6 +38,15 @@
  *     content: string,
  *     type: string,
  * }
+ *
+ * @psalm-type FilesFolderTreeNode = array{
+ *     id: int,
+ *     displayName?: string,
+ *     children?: array<string, array{}>,
+ * }
+ *
+ * @psalm-type FilesFolderTree = array<string, FilesFolderTreeNode>
+ *
  */
 class ResponseDefinitions {
 }
diff --git a/apps/files/openapi.json b/apps/files/openapi.json
@@ -99,6 +99,33 @@
                     }
                 }
             },
+            "FolderTree": {
+                "type": "object",
+                "additionalProperties": {
+                    "$ref": "#/components/schemas/FolderTreeNode"
+                }
+            },
+            "FolderTreeNode": {
+                "type": "object",
+                "required": [
+                    "id"
+                ],
+                "properties": {
+                    "id": {
+                        "type": "integer",
+                        "format": "int64"
+                    },
+                    "displayName": {
+                        "type": "string"
+                    },
+                    "children": {
+                        "type": "object",
+                        "additionalProperties": {
+                            "type": "object"
+                        }
+                    }
+                }
+            },
             "OCSMeta": {
                 "type": "object",
                 "required": [
@@ -1928,6 +1955,65 @@
                     }
                 }
             }
+        },
+        "/ocs/v2.php/apps/files/api/v1/folder-tree": {
+            "get": {
+                "operationId": "api-get-folder-tree",
+                "summary": "Returns the folder tree of the user",
+                "tags": [
+                    "api"
+                ],
+                "security": [
+                    {
+                        "bearer_auth": []
+                    },
+                    {
+                        "basic_auth": []
+                    }
+                ],
+                "parameters": [
+                    {
+                        "name": "OCS-APIRequest",
+                        "in": "header",
+                        "description": "Required to be true for the API request to pass",
+                        "required": true,
+                        "schema": {
+                            "type": "boolean",
+                            "default": true
+                        }
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "Folder tree returned successfully",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/FolderTree"
+                                }
+                            }
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "type": "object",
+                                    "required": [
+                                        "message"
+                                    ],
+                                    "properties": {
+                                        "message": {
+                                            "type": "string"
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
         }
     },
     "tags": []