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