Merge pull request #12004 from opf/implementation/45954-extend-openapi-spec-for-storage-files-endpoint

[#45954] Extend OpenAPI spec for storage files endpoint

docs/api/apiv3/components/schemas/file_collection_model.yml

@@ -1,64 +0,0 @@
-# Schema: FileCollectionModel
----
-allOf:
-  - $ref: './collection_model.yml'
-  - type: object
-    required:
-      - _links
-      - _embedded
-    properties:
-      _links:
-        type: object
-        required:
-          - self
-        properties:
-          self:
-            allOf:
-              - $ref: './link.yml'
-              - description: |-
-                  This file collection
-                  
-                  **Resource**: FileCollectionModel
-      _embedded:
-        type: object
-        required:
-          - elements
-        properties:
-          elements:
-            type: array
-            items:
-              $ref: './storage_file_model.yml'
-
-example:
-  _type: Collection
-  total: 2
-  count: 2
-  _links:
-    self:
-      href: '/api/v3/storages/42/files'
-  _embedded:
-    elements:
-      - id: 1337
-        location: '/data/logo.png'
-        name: logo.png
-        mimeType: image/png
-        size: 16042
-        createdAt: '2021-12-19T09:42:10.170Z'
-        lastModifiedAt: '2021-12-20T14:00:13.987Z'
-        createdByName: Luke Skywalker
-        lastModifiedByName: Anakin Skywalker
-        _links:
-          self:
-            href: 'urn:openproject-org:api:v3:storages:storage_file:no_link_provided'
-      - id: 1338
-        location: '1338'
-        name: README.md
-        mimeType: text/markdown
-        size: 3742
-        createdAt: '2021-12-20T09:42:10.170Z'
-        lastModifiedAt: '2021-12-21T14:00:13.987Z'
-        createdByName: Leia Organa
-        lastModifiedByName: Leia Organa
-        _links:
-          self:
-            href: 'urn:openproject-org:api:v3:storages:storage_file:no_link_provided'

docs/api/apiv3/components/schemas/storage_file_location_model.yml

@@ -1,22 +0,0 @@
-# Schema: StorageFileLocationModel
----
-type: object
-required:
-  - location
-properties:
-  location:
-    type: string
-    description: Location identification for file in storage
-  _links:
-    type: object
-    required:
-      - self
-    properties:
-      self:
-        allOf:
-          - "$ref": "./link.yml"
-          - description: |-
-              Not provided
-              
-              **Resource**: urn:openproject-org:api:v3:storages:storage_file:no_link_provided
-            readOnly: true

docs/api/apiv3/components/schemas/storage_file_model.yml

@@ -2,4 +2,36 @@
 ---
 allOf:
   - $ref: './file_link_origin_data_model.yml'
-  - $ref: './storage_file_location_model.yml'
+  - type: object
+    required:
+      - _type
+      - location
+      - _links
+    properties:
+      _type:
+        type: string
+        enum:
+          - StorageFile
+      location:
+        type: string
+        description: Location identification for file in storage
+      _links:
+        type: object
+        required:
+          - self
+        properties:
+          self:
+            allOf:
+              - $ref: './link.yml'
+              - description: |-
+                  Not provided
+
+                  **Resource**: urn:openproject-org:api:v3:storages:storage_file:no_link_provided
+example:
+  id: 42
+  name: readme.md
+  _type: StorageFile
+  location: '/readme.md'
+  _links:
+    self:
+      href: 'urn:openproject-org:api:v3:storages:storage_file:no_link_provided'

docs/api/apiv3/components/schemas/storage_files_model.yml

@@ -0,0 +1,80 @@
+# Schema: StorageFilesModel
+---
+type: object
+required:
+  - _type
+  - files
+  - parent
+  - _links
+properties:
+  _type:
+    type: string
+    enum:
+      - StorageFiles
+  files:
+    type: array
+    items:
+      $ref: './storage_file_model.yml'
+    description: List of files provided by the selected storage.
+  parent:
+    allOf:
+      - $ref: './storage_file_model.yml'
+      - description: File of the currently selected parent directory.
+  _links:
+    type: object
+    required:
+      - self
+    properties:
+      self:
+        allOf:
+          - $ref: "./link.yml"
+          - description: |-
+              Not provided
+              
+              **Resource**: urn:openproject-org:api:v3:storages:storage_file:no_link_provided
+example:
+  _type: StorageFiles
+  files:
+    - id: 42
+      name: readme.md
+      _type: StorageFile
+      location: '/readme.md'
+      mimeType: 'text/markdown'
+      size: 4096
+      createdAt: '2021-12-19T09:42:10.170Z'
+      lastModifiedAt: '2021-12-20T14:00:13.987Z'
+      createdByName: Luke Skywalker
+      lastModifiedByName: Anakin Skywalker
+      _links:
+        self:
+          href: 'urn:openproject-org:api:v3:storages:storage_file:no_link_provided'
+    - id: 43
+      name: readme.pdf
+      _type: StorageFile
+      location: '/readme.pdf'
+      mimeType: 'application/pdf'
+      size: 2048
+      createdAt: '2021-12-19T09:42:10.170Z'
+      lastModifiedAt: '2021-12-20T14:00:13.987Z'
+      createdByName: Luke Skywalker
+      lastModifiedByName: Anakin Skywalker
+      _links:
+        self:
+          href: 'urn:openproject-org:api:v3:storages:storage_file:no_link_provided'
+  parent:
+    id: 41
+    name: '/'
+    location: '/'
+    mimeType: 'application/x-op-directory'
+    size: 6144
+    createdAt: '2021-12-20T09:42:10.170Z'
+    lastModifiedAt: '2021-12-21T14:00:13.987Z'
+    createdByName: Luke Skywalker
+    lastModifiedByName: Anakin Skywalker
+    _links:
+      self:
+        href: 'urn:openproject-org:api:v3:storages:storage_file:no_link_provided'
+  _links:
+    self:
+      href: 'urn:openproject-org:api:v3:storages:storage_file:no_link_provided'
+  

docs/api/apiv3/openapi-spec.yml

@@ -584,8 +584,6 @@ components:
       "$ref": "./components/schemas/example_schema_model.yml"
     Execute_custom_action:
       "$ref": "./components/schemas/execute_custom_action.yml"
-    FileCollectionModel:
-      $ref: './components/schemas/file_collection_model.yml'
     FileLinkCollectionReadModel:
       $ref: './components/schemas/file_link_collection_read_model.yml'
     FileLinkCollectionWriteModel:
@@ -750,8 +748,8 @@ components:
       "$ref": "./components/schemas/statuses_model.yml"
     StorageFileModel:
       "$ref": "./components/schemas/storage_file_model.yml"
-    StorageFileLocationModel:
+    StorageFilesModel:
-      "$ref": "./components/schemas/storage_file_location_model.yml"
+      "$ref": "./components/schemas/storage_files_model.yml"
     StorageFileUploadPreparationModel:
       "$ref": "./components/schemas/storage_file_upload_preparation_model.yml"
     StorageFileUploadLinkModel:

docs/api/apiv3/paths/storage_files.yml

@@ -33,7 +33,7 @@ get:
       content:
         application/hal+json:
           schema:
-            $ref: '../components/schemas/file_collection_model.yml'
+            $ref: '../components/schemas/storage_files_model.yml'
     '400':
       description: Returned if the given parent parameter value does not refer to a directory.
       content: