From f3782e738768210ff039faefb4c8ceb6c644a0b0 Mon Sep 17 00:00:00 2001
From: Bruno Pagno <b.pagno@openproject.com>
Date: Thu, 5 Dec 2024 15:45:26 +0100
Subject: [PATCH] write specification for new folder API endpoint

---
 .../storage-create-folder-request-body.yml    |  5 ++
 .../schemas/storage_folder_write_model.yml    | 13 ++++
 docs/api/apiv3/openapi-spec.yml               |  6 ++
 docs/api/apiv3/paths/storage_folders.yml      | 68 +++++++++++++++++++
 4 files changed, 92 insertions(+)
 create mode 100644 docs/api/apiv3/components/examples/storage-create-folder-request-body.yml
 create mode 100644 docs/api/apiv3/components/schemas/storage_folder_write_model.yml
 create mode 100644 docs/api/apiv3/paths/storage_folders.yml

diff --git a/docs/api/apiv3/components/examples/storage-create-folder-request-body.yml b/docs/api/apiv3/components/examples/storage-create-folder-request-body.yml
new file mode 100644
index 000000000000..dad2d8b2e047
--- /dev/null
+++ b/docs/api/apiv3/components/examples/storage-create-folder-request-body.yml
@@ -0,0 +1,5 @@
+description: |-
+  A valid request body to create a new folder on a external storage
+value:
+  name: Uploads
+  parentId: "200"
diff --git a/docs/api/apiv3/components/schemas/storage_folder_write_model.yml b/docs/api/apiv3/components/schemas/storage_folder_write_model.yml
new file mode 100644
index 000000000000..bcdef5c9e552
--- /dev/null
+++ b/docs/api/apiv3/components/schemas/storage_folder_write_model.yml
@@ -0,0 +1,13 @@
+# Schema: StorageFolderWriteModel
+---
+type: object
+required:
+  - name
+  - parentId
+properties:
+  name:
+    type: string
+    description: Name of the folder to be created
+  parentId:
+    type: string
+    description: Unique identifier of the parent folder in which the new folder should be created in
diff --git a/docs/api/apiv3/openapi-spec.yml b/docs/api/apiv3/openapi-spec.yml
index e3afad89a8f4..7cba8c52b76d 100644
--- a/docs/api/apiv3/openapi-spec.yml
+++ b/docs/api/apiv3/openapi-spec.yml
@@ -392,6 +392,8 @@ paths:
     "$ref": "./paths/storage_files.yml"
   "/api/v3/storages/{id}/files/prepare_upload":
     "$ref": "./paths/storage_files_prepare_upload.yml"
+  "/api/v3/storages/{id}/folders":
+    "$ref": "./paths/storage_folders.yml"
   "/api/v3/storages/{id}/oauth_client_credentials":
     "$ref": "./paths/storage_oauth_client_credentials.yml"
   "/api/v3/storages/{id}/open":
@@ -545,6 +547,8 @@ components:
       $ref: "./components/examples/status_response.yml"
     StorageNextcloudResponse:
       $ref: "./components/examples/storage-nextcloud-response.yml"
+    StorageCreateFolderRequestBody:
+      $ref: "./components/examples/storage-create-folder-request-body.yml"
     StorageNextcloudResponseForCreation:
       $ref: "./components/examples/storage-nextcloud-response-for-creation.yml"
     StorageNextcloudUnauthorizedResponse:
@@ -825,6 +829,8 @@ components:
       "$ref": "./components/schemas/storage_file_model.yml"
     StorageFilesModel:
       "$ref": "./components/schemas/storage_files_model.yml"
+    StorageFolderWriteModel:
+      "$ref": "./components/schemas/storage_folder_write_model.yml"
     StorageFileUploadPreparationModel:
       "$ref": "./components/schemas/storage_file_upload_preparation_model.yml"
     StorageFileUploadLinkModel:
diff --git a/docs/api/apiv3/paths/storage_folders.yml b/docs/api/apiv3/paths/storage_folders.yml
new file mode 100644
index 000000000000..1e22c776775f
--- /dev/null
+++ b/docs/api/apiv3/paths/storage_folders.yml
@@ -0,0 +1,68 @@
+# /api/v3/storages/{id}/folders
+---
+post:
+  summary: Creation of a new folder
+  operationId: create_storage_folder
+  tags:
+    - File links
+  description: Creates a new folder under the given parent
+  parameters:
+    - name: id
+      description: Storage id
+      in: path
+      required: true
+      schema:
+        type: integer
+      example: 1337
+  requestBody:
+    content:
+      application/json:
+        schema:
+          $ref: '../components/schemas/storage_folder_write_model.yml'
+        examples:
+          'Valid example':
+            $ref: '../components/examples/storage-create-folder-request-body.yml'
+  responses:
+    '201':
+      description: Created
+      content:
+        application/hal+json:
+          schema:
+            $ref: '../components/schemas/storage_file_model.yml'
+    '400':
+      content:
+        application/hal+json:
+          schema:
+            $ref: '../components/schemas/error_response.yml'
+          example:
+            _type: Error
+            errorIdentifier: urn:openproject-org:api:v3:errors:InvalidQuery
+            message: The given parent is not a directory.
+      description: |-
+        Returned if the request is missing a required parameter.
+    '403':
+      content:
+        application/hal+json:
+          schema:
+            $ref: '../components/schemas/error_response.yml'
+          example:
+            _type: Error
+            errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
+            message: You are not authorized to access this resource.
+      description: |-
+        Returned if the client does not have sufficient permissions.
+
+        **Required permission:** manage file links
+    '404':
+      content:
+        application/hal+json:
+          schema:
+            $ref: '../components/schemas/error_response.yml'
+          example:
+            _type: Error
+            errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
+            message: The requested resource could not be found.
+      description: |-
+        Returned if the storage does not exist or the client does not have sufficient permissions to see it.
+
+        **Required permission:** view file links