[#42161] added additional link to file link model

- https://community.openproject.org/work_packages/42161
- file link read model now contains a link to file location
- some boyscouting in root model, fixed 2 warnings

.redocly.lint-ignore.yaml

@@ -5,4 +5,5 @@ tmp/oas-generated.yml:
     - '#/paths/~1api~1v3~1work_packages~1{id}~1relations/get/responses'
     - '#/paths/~1api~1v3~1file_links~1{file_link_id}~1open/get/responses'
   operation-4xx-response:
+    - '#/paths/~1api~1v3/get/responses'
     - '#/paths/~1api~1v3~1work_packages~1{id}~1relations/get/responses'

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

@@ -42,6 +42,8 @@ properties:
       - creator
       - originOpen
       - staticOriginOpen
+      - originOpenLocation
+      - staticOriginOpenLocation
     properties:
       self:
         allOf:
@@ -93,6 +95,20 @@ properties:
           - description: |-
               A static uri to open the origin file on the storage. Responds with a redirect.
               
+              **Resource**: N/A
+      originOpenLocation:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              The uri to open the location of origin file on the origin itself.
+              
+              **Resource**: N/A
+      staticOriginOpenLocation:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              A static uri to open the location of the origin file on the storage. Responds with a redirect.
+              
               **Resource**: N/A
 
 example:
@@ -162,8 +178,14 @@ example:
       href: /api/v3/work_package/17/file_links/1337
       title: file link delete API
     originOpen:
-      href: https://nextcloud.deathstar.rocks/index.php/f?fileid=5503
+      href: https://nextcloud.deathstar.rocks/index.php/f?fileid=5503openfile=1
       title: file open
     staticOriginOpen:
       href: /api/v3/work_package/17/file_links/1337/open
       title: file open
+    originOpenLocation:
+      href: https://nextcloud.deathstar.rocks/index.php/f?fileid=5503&openfile=0
+      title: file open
+    staticOriginOpenLocation:
+      href: /api/v3/work_package/17/file_links/1337/open?location=true
+      title: file open

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

@@ -1,11 +1,18 @@
 # Schema: RootModel
 ---
 type: object
+required:
+  - _type
+  - instanceName
+  - _links
 properties:
+  _type:
+    type: string
+    enum:
+      - Root
   instanceName:
     type: string
     description: The name of the OpenProject instance
-    readOnly: true
   coreVersion:
     type: string
     description: |-
@@ -14,26 +21,124 @@ properties:
       # Conditions
 
       **Permission** requires admin privileges
-example:
   _links:
+    type: object
+    required:
+      - self
+      - configuration
+      - memberships
+      - priorities
+      - relations
+      - statuses
+      - time_entries
+      - types
+      - user
+      - userPreferences
+      - workPackages
+    properties:
+      self:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              This root information object.
+              
+              **Resource**: Root
       configuration:
-      href: "/api/v3/configuration"
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              The configuration resource.
+              
+              **Resource**: Configuration
+      memberships:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              The collection of memberships.
+              
+              **Resource**: Collection
+      priorities:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              The collection of priorities.
+              
+              **Resource**: Collection
+      relations:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              The collection of relations.
+              
+              **Resource**: Collection
+      statuses:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              The collection of statuses.
+              
+              **Resource**: Collection
+      time_entries:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              The collection of time entries.
+              
+              **Resource**: Collection
+      types:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              The collection of types.
+              
+              **Resource**: Collection
       user:
-      href: "/api/v3/users/1"
+        allOf:
-      title: John Sheppard
+          - $ref: './link.yml'
+          - description: |-
+              The current user resource.
+              
+              **Resource**: User
       userPreferences:
-      href: "/api/v3/my_preferences"
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              The current user preferences resource.
+              
+              **Resource**: UserPreferences
+      workPackages:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              The work package collection.
+              
+              **Resource**: Collection
+
+example:
+  _type: Root
+  instanceName: OpenProject
+  coreVersion: 12.1.0
+  _links:
+    self:
+      href: '/api/v3'
+    configuration:
+      href: '/api/v3/configuration'
+    memberships:
+      href: '/api/v3/memberships'
     priorities:
-      href: "/api/v3/priorities"
+      href: '/api/v3/priorities'
     relations:
-      href: "/api/v3/relations"
+      href: '/api/v3/relations'
     statuses:
-      href: "/api/v3/statuses"
+      href: '/api/v3/statuses'
+    time_entries:
+      href: '/api/v3/time_entries'
     types:
-      href: "/api/v3/types"
+      href: '/api/v3/types'
+    user:
+      href: '/api/v3/users/3'
+      title: Anakin Skywalker
+    userPreferences:
+      href: '/api/v3/users/3/preferences'
     workPackages:
-      href: "/api/v3/work_packages"
+      href: '/pi/v3/work_packages'
-    users:
-      href: "/api/v3/users"
-  instanceName: My own OpenProject
-  coreVersion: 10.3.0

docs/api/apiv3/paths/file_link_open.yml

@@ -17,6 +17,13 @@ get:
       schema:
         type: integer
       example: 42
+    - name: location
+      description: Boolean flag indicating, if the file should be opened directly or rather the directory location.
+      in: query
+      required: false
+      schema:
+        type: boolean
+      example: true
   responses:
     '303':
       headers:

docs/api/apiv3/paths/root.yml

@@ -1,41 +1,16 @@
 # /api/v3
 ---
 get:
+  summary: View root
+  operationId: view_root
+  description: |-
+    Returns the root resource, containing basic information about the server instance and a collection of useful links.
+  tags:
+    - Root
   responses:
     '200':
+      description: OK
       content:
         application/hal+json:
-          examples:
-            response:
-              value:
-                _links:
-                  configuration:
-                    href: "/api/v3/configuration"
-                  priorities:
-                    href: "/api/v3/priorities"
-                  relations:
-                    href: "/api/v3/relations"
-                  statuses:
-                    href: "/api/v3/statuses"
-                  types:
-                    href: "/api/v3/types"
-                  user:
-                    href: "/api/v3/users/1"
-                    title: John Sheppard
-                  userPreferences:
-                    href: "/api/v3/my_preferences"
-                  users:
-                    href: "/api/v3/users"
-                  workPackages:
-                    href: "/api/v3/work_packages"
-                coreVersion: 10.3.0
-                instanceName: My own OpenProject
           schema:
-            "$ref": "../components/schemas/root_model.yml"
+            $ref: '../components/schemas/root_model.yml'
-      description: OK
-      headers: {}
-  tags:
-  - Root
-  description: ''
-  operationId: View_root
-  summary: View root