[#50543] amended api spec

.redocly.lint-ignore.yaml

@@ -2,11 +2,14 @@ tmp/oas-generated.yml:
   info-license:
     - '#/info'
   operation-2xx-response:
-    - '#/paths/~1api~1v3~1work_packages~1{id}~1relations/get/responses'
     - '#/paths/~1api~1v3~1file_links~1{file_link_id}~1open/get/responses'
+    - '#/paths/~1api~1v3~1project_storages~1{id}~1open/get/responses'
+    - '#/paths/~1api~1v3~1storages~1{id}~1open/get/responses'
+    - '#/paths/~1api~1v3~1work_packages~1{id}~1relations/get/responses'
   operation-4xx-response:
     - '#/paths/~1api~1v3/get/responses'
     - '#/paths/~1api~1v3~1help_texts/get/responses'
+    - '#/paths/~1api~1v3~1work_packages~1form/post/responses'
   no-ambiguous-paths:
     - '#/paths/~1api~1v3~1queries~1{id}~1form'
     - '#/paths/~1api~1v3~1queries~1{id}~1star'

docs/api/apiv3/openapi-spec.yml

@@ -270,6 +270,8 @@ paths:
     "$ref": "./paths/project_storages.yml"
   "/api/v3/project_storages/{id}":
     "$ref": "./paths/project_storage.yml"
+  "/api/v3/project_storages/{id}/open":
+    "$ref": "./paths/project_storage_open.yml"
   "/api/v3/projects":
     "$ref": "./paths/projects.yml"
   "/api/v3/projects/form":
@@ -374,6 +376,8 @@ paths:
     "$ref": "./paths/storage_files_prepare_upload.yml"
   "/api/v3/storages/{id}/oauth_client_credentials":
     "$ref": "./paths/storage_oauth_client_credentials.yml"
+  "/api/v3/storages/{id}/open":
+    "$ref": "./paths/storage_open.yml"
   "/api/v3/time_entries":
     "$ref": "./paths/time_entries.yml"
   "/api/v3/time_entries/{id}/form":

docs/api/apiv3/paths/project_storage_open.yml

@@ -0,0 +1,50 @@
+# /api/v3/project_storage/{id}/open
+---
+get:
+  summary: Open the project storage
+  operationId: open_project_storage
+  tags:
+    - File Links
+  description: |-
+    Gets a redirect to the location of the project storage's remote origin. If the project storage has a project
+    folder, it is opened at this location. If not, the storage root is opened.
+  parameters:
+    - name: id
+      description: Project storage id
+      in: path
+      required: true
+      schema:
+        type: integer
+      example: 1337
+  responses:
+    '303':
+      description: Redirect
+      headers:
+        Location:
+          schema:
+            type: string
+            format: uri
+    '403':
+      content:
+        application/hal+json:
+          schema:
+            $ref: '../components/schemas/error_response.yml'
+          example:
+            _type: Error
+            errorIdentifier: urn:openproject-org:api:v3:errors:Unauthenticated
+            message: You are not authorized to access this resource.
+      description: |-
+        Returned if the authorization token of the current user grants no permission to access the remote storage.
+    '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 project storage does not exist or the client does not have sufficient permissions to see it.
+
+        **Required permission:** view file links

docs/api/apiv3/paths/storage_open.yml

@@ -0,0 +1,39 @@
+# /api/v3/storage/{id}/open
+---
+get:
+  summary: Open the storage
+  operationId: open_storage
+  tags:
+    - File Links
+  description: |-
+    Gets a redirect to the location of the storage's remote origin. The storage's files root should be the target
+    location.
+  parameters:
+    - name: id
+      description: Storage id
+      in: path
+      required: true
+      schema:
+        type: integer
+      example: 1337
+  responses:
+    '303':
+      description: Redirect
+      headers:
+        Location:
+          schema:
+            type: string
+            format: uri
+    '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