Merge pull request #16362 from opf/bug/40942-openapi-specs-wrong-for-…

…creating-work-package-relations

[#40942] documented API behaviour for relation creation

docs/api/apiv3/components/examples/relation_collection_response.yml

@@ -1,5 +1,5 @@
-# Example: Relation Collection
----
+description: |-
+  Simple response of a relation collection.
 value:
   _type: Collection
   total: 40

docs/api/apiv3/components/examples/relation_create_request.yml

@@ -0,0 +1,9 @@
+description: |-
+  Example request to create a relation between two work packages.
+value:
+  type: follows
+  lag: 2
+  description: Build hangar AFTER improving external skeleton of Death Star.
+  _links:
+    to:
+      href: /api/v3/work_packages/1337

docs/api/apiv3/components/examples/relation_response.yml

@@ -1,5 +1,5 @@
-# Example: Relation
----
+description: |-
+  Simple response of a 'duplicated by' relation between two work packages.
 value:
   _type: Relation
   id: 650

docs/api/apiv3/components/examples/relation_update_request.yml

@@ -0,0 +1,4 @@
+description: |-
+  Example request to update the relation's description.
+value:
+  description: This is the new description.

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

@@ -27,4 +27,4 @@ allOf:
           elements:
             type: array
             items:
-              $ref: './relation_model.yml'
+              $ref: './relation_read_model.yml'

docs/api/apiv3/components/schemas/relation_model.yml → docs/api/apiv3/components/schemas/relation_read_model.yml

@@ -1,9 +1,6 @@
-# Schema: RelationModel
+# Schema: RelationReadModel
 ---
 type: object
-required:
-  - _type
-  - id
 properties:
   _type:
     type: string
@@ -14,7 +11,7 @@ properties:
     description: Relation ID
   name:
     type: string
-    description: The internationalized name of this type of relation
+    description: The internationalised name of this type of relation
   type:
     type: string
     description: The relation type.
@@ -47,13 +44,13 @@ properties:
       - required
   description:
     type:
-      - string
-      - null
+      - 'string'
+      - 'null'
     description: A descriptive text for the relation.
   lag:
     type:
-      - integer
-      - null
+      - 'integer'
+      - 'null'
     description: The lag in days between closing of `from` and start of `to`
     minimum: 0
   _embedded:
@@ -65,87 +62,55 @@ properties:
         $ref: './work_package_model.yml'
   _links:
     type: object
-    required:
-      - self
-      - schema
-      - from
-      - to
     properties:
       self:
         allOf:
           - $ref: './link.yml'
           - description: |-
               This relation
-              
+
               **Resource**: Relation
-              
+
               # Conditions
-              
+
               **Permission**: view work packages
       updateImmediately:
         allOf:
           - $ref: './link.yml'
           - description: |-
               Updates the relation between two work packages
-              
+
               # Conditions
-              
+
               **Permission**: manage work package relations
       delete:
         allOf:
           - $ref: './link.yml'
           - description: |-
               Destroys the relation between the two work packages
-              
+
               # Conditions
-              
+
               **Permission**: manage work package relations
       from:
         allOf:
           - $ref: './link.yml'
           - description: |-
               The emanating work package
-              
+
               **Resource**: WorkPackage
-              
+
               # Conditions
-              
+
               **Permission**: view work packages
       to:
         allOf:
           - $ref: './link.yml'
           - description: |-
               The work package the relation ends in
-              
+
               **Resource**: WorkPackage
-              
+
               # Conditions
-              
-              **Permission**: view work packages
 
-example:
-  _links:
-    self:
-      href: "/api/v3/relations/1"
-    update:
-      href: "/api/v3/relations/1/form"
-      method: POST
-    updateImmediately:
-      href: "/api/v3/relations/1"
-      method: PATCH
-    delete:
-      href: "/api/v3/relations/1"
-      method: DELETE
-    from:
-      href: "/api/v3/work_packages/42"
-      title: Steel Delivery
-    to:
-      href: "/api/v3/work_packages/84"
-      title: Bending the steel
-  _type: Relation
-  id: 1
-  name: precedes
-  type: precedes
-  reverseType: follows
-  description: We can't bend the steel before it's been delivered!
-  lag: 0
+              **Permission**: view work packages

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

@@ -0,0 +1,47 @@
+# Schema: RelationWriteModel
+---
+type: object
+required:
+  - _links
+  - type
+properties:
+  type:
+    type: string
+    description: The relation type.
+    enum:
+      - relates
+      - duplicates
+      - duplicated
+      - blocks
+      - blocked
+      - precedes
+      - follows
+      - includes
+      - partof
+      - requires
+      - required
+  description:
+    type:
+      - 'string'
+      - 'null'
+    description: A descriptive text for the relation.
+  lag:
+    type:
+      - 'integer'
+      - 'null'
+    description: The lag in days between closing of `from` and start of `to`
+    minimum: 0
+  _links:
+    type: object
+    properties:
+      to:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              The work package the relation ends in. Only available on relation creation, not on update.
+              
+              **Resource**: WorkPackage
+              
+              # Conditions
+              
+              **Permission**: view work packages

docs/api/apiv3/openapi-spec.yml

@@ -521,8 +521,12 @@ components:
       $ref: "./components/examples/project_collection.yml"
     RelationCollectionResponse:
       $ref: "./components/examples/relation_collection_response.yml"
+    RelationCreateRequest:
+      $ref: "./components/examples/relation_create_request.yml"
     RelationResponse:
       $ref: "./components/examples/relation_response.yml"
+    RelationUpdateRequest:
+      $ref: "./components/examples/relation_update_request.yml"
     StorageNextcloudResponse:
       $ref: "./components/examples/storage-nextcloud-response.yml"
     StorageNextcloudResponseForCreation:
@@ -757,8 +761,10 @@ components:
       "$ref": "./components/schemas/query_update_form.yml"
     RelationCollectionModel:
       "$ref": "./components/schemas/relation_collection_model.yml"
-    RelationModel:
-      "$ref": "./components/schemas/relation_model.yml"
+    RelationReadModel:
+      "$ref": "./components/schemas/relation_read_model.yml"
+    RelationWriteModel:
+      "$ref": "./components/schemas/relation_write_model.yml"
     RevisionModel:
       "$ref": "./components/schemas/revision_model.yml"
     RevisionsModel:

docs/api/apiv3/paths/relation.yml

@@ -23,7 +23,7 @@ get:
             response:
               $ref: '../components/examples/relation_response.yml'
           schema:
-            $ref: '../components/schemas/relation_model.yml'
+            $ref: '../components/schemas/relation_read_model.yml'
     '404':
       description: |-
         Returned if the relation does not exist or the client does not have sufficient permissions to see it.
@@ -104,6 +104,8 @@ patch:
     Note that changing the `type` of a relation invariably also changes the respective `reverseType` as well as the
     "name" of it. The returned Relation object will reflect that change. For instance if you change a Relation's
     `type` to "follows" then the `reverseType` will be changed to `precedes`.
+    
+    It is not allowed to change a relation's involved work packages.
   parameters:
     - description: Relation ID
       example: '1'
@@ -112,13 +114,21 @@ patch:
       required: true
       schema:
         type: integer
+  requestBody:
+    content:
+      application/json:
+        schema:
+          $ref: '../components/schemas/relation_write_model.yml'
+        examples:
+          request:
+            $ref: '../components/examples/relation_update_request.yml'
   responses:
     '200':
       description: OK
       content:
         application/hal+json:
           schema:
-            $ref: '../components/schemas/relation_model.yml'
+            $ref: '../components/schemas/relation_read_model.yml'
           examples:
             response:
               $ref: '../components/examples/relation_response.yml'