From 5d95c7333e95063b026e460a6f5513a4b97498a4 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/paths/storage_folders.yml      | 68 +++++++++++++++++++
 3 files changed, 86 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/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