Merge pull request #16527 from opf/bug/40945-api-description-and-open…

…api-spec-not-consistent

[#40945] updated work package form API specs

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

@@ -0,0 +1,5 @@
+description: |-
+  A request body to create a work package with only a subject. This can only be used, if the project context is already
+  given in the path. All other values will fall back to defaults.
+value:
+  subject: Replace GNK power droids

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

@@ -0,0 +1,20 @@
+description: |-
+  A valid request body to create or edit a work package with a couple of properties.
+value:
+  subject: Install Dromund Kass planetary shield
+  description: 
+    format: markdown
+    raw: |-
+      # TODO
+      
+      The planetary shield of Dromund Kass needs to be installed to protect the planet from orbital bombardment.
+  startDate: '2877-07-21'
+  duration: P1337D
+  estimatedTime: P1Y5DT13H
+  ignoreNonWorkingDays: true
+  project:
+    href: /api/v3/projects/42
+  type:
+    href: /api/v3/types/13
+  status:
+    href: /api/v3/statuses/2

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

@@ -0,0 +1,4 @@
+description: |-
+  A request body to edit a work package's subject.
+value:
+  subject: Replace GNK power droids

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

@@ -0,0 +1,53 @@
+# Schema: WorkPackageFormModel
+---
+type: object
+description: |-
+  The work package creation form. This object is returned, whenever a work package form endpoint is called. It contains
+  an allowed payload definition, the full schema and any validation errors on the current request body.
+properties:
+  _type:
+    type: string
+    enum:
+      - Form
+  _embedded:
+    type: object
+    properties:
+      payload:
+        $ref: './work_package_write_model.yml'
+      schema:
+        $ref: './work_package_schema_model.yml'
+      validationErrors:
+        type: object
+        description: |-
+          All validation errors, where the key is the faulty property. The object is empty, if the request body is
+          valid.
+  _links:
+    type: object
+    properties:
+      self:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              This form endpoint
+              
+              **Resource** : Form
+      validate:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              The endpoint for validating the request bodies. Often referring to this very form endpoint.
+      previewMarkup:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              Renders a markup preview for the work package form.
+      customFields:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              Link to the HTML page for the custom field definitions.
+      configureForm:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              Link to the HTML page for the form configuration.

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

@@ -1,176 +1,11 @@
 # Schema: WorkPackagePatchModel
 ---
-type: object
-required:
-  - lockVersion
-properties:
-  lockVersion:
-    type: integer
-    description: The version of the item as used for optimistic locking
-  subject:
-    type: string
-    description: Work package subject
-  description:
-    allOf:
-      - $ref: "./formattable.yml"
-      - description: The work package description
-  scheduleManually:
-    type: boolean
-    description: If false (default) schedule automatically.
-  startDate:
-    type: string
-    format: date
-    description: Scheduled beginning of a work package
-  dueDate:
-    type: string
-    format: date
-    description: Scheduled end of a work package
-  date:
-    type: string
-    format: date
-    description: Date on which a milestone is achieved
-  estimatedTime:
-    type: string
-    format: duration
-    description: Time a work package likely needs to be completed excluding its descendants
-  ignoreNonWorkingDays:
-    type: boolean
-    description: |-
-      **(NOT IMPLEMENTED)** When scheduling, whether or not to ignore the non working days being defined.
-      A work package with the flag set to true will be allowed to be scheduled to a non working day.
-    readOnly: true
-  spentTime:
-    type: string
-    format: duration
-    description: |-
-      The time booked for this work package by users working on it
-
-      # Conditions
-
-      **Permission** view time entries
-    readOnly: true
-  percentageDone:
-    type: integer
-    description: Amount of total completion for a work package
-    maximum: 100
-  createdAt:
-    type: string
-    format: date-time
-    description: Time of creation
-    readOnly: true
-  updatedAt:
-    type: string
-    format: date-time
-    description: Time of the most recent change to the work package
-    readOnly: true
-  _links:
-    type: object
+allOf:
+  - $ref: './work_package_write_model.yml'
+  - type: object
+    required:
+      - lockVersion
     properties:
-      assignee:
-        allOf:
-          - $ref: "./link.yml"
-          - description: |-
-              The person that is intended to work on the work package
-              
-              **Resource**: User
-      budget:
-        allOf:
-          - $ref: "./link.yml"
-          - description: |-
-              The budget this work package is associated to
-              
-              **Resource**: Budget
-              
-              # Conditions
-              
-              **Permission** view cost objects
-      category:
-        allOf:
-          - $ref: "./link.yml"
-          - description: |-
-              The category of the work package
-              
-              **Resource**: Category
-      parent:
-        allOf:
-          - $ref: "./link.yml"
-          - description: |-
-              Parent work package
-              
-              **Resource**: WorkPackage
-      priority:
-        allOf:
-          - $ref: "./link.yml"
-          - description: |-
-              The priority of the work package
-              
-              **Resource**: Priority
-      project:
-        allOf:
-          - $ref: "./link.yml"
-          - description: |-
-              The project to which the work package belongs
-              
-              **Resource**: Project
-      responsible:
-        allOf:
-          - $ref: "./link.yml"
-          - description: |-
-              The person that is responsible for the overall outcome
-              
-              **Resource**: User
-      status:
-        allOf:
-          - $ref: "./link.yml"
-          - description: |-
-              The current status of the work package
-              
-              **Resource**: Status
-      type:
-        allOf:
-          - $ref: "./link.yml"
-          - description: |-
-              The type of the work package
-              
-              **Resource**: Type
-      version:
-        allOf:
-          - $ref: "./link.yml"
-          - description: |-
-              The version associated to the work package
-              
-              **Resource**: Version
-
-examples:
-  - subject: Upgrade hangar 25
-    lockVersion: 0
-    description:
-      format: markdown
-      raw: we need more place for new TIE Advanced
-      html: "<p>we need more place for new TIE Advanced</p>"
-    scheduleManually: false
-    _links:
-      responsible:
-        href: "/api/v3/users/23"
-        title: Palpatine
-      assignee:
-        href: "/api/v3/users/33"
-        title: Darth Vader
-      priority:
-        href: "/api/v3/priorities/2"
-        title: Normal
-      project:
-        href: "/api/v3/projects/1"
-        title: Galactic Conquest
-      status:
-        href: "/api/v3/statuses/1"
-        title: New
-      type:
-        href: "/api/v3/types/11"
-        title: DeathStarUpgrades
-      version:
-        href: "/api/v3/versions/1"
-        title: Version 1
-      parent:
-        href: "/api/v3/work_packages/1298"
-        title: ct'hulhu f'tagn
+      lockVersion:
+        type: integer
+        description: The version of the item as used for optimistic locking

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

@@ -0,0 +1,92 @@
+# Schema: WorkPackageSchemaModel
+---
+type: object
+description: |-
+  A schema for a work package. This schema defines the attributes of a work package.
+  
+  TODO: Incomplete, needs to be updated with the real behaviour of schemas (when does which attribute appear?).
+properties:
+  _type:
+    type: string
+    enum:
+      - Schema
+  _dependencies:
+    type: array
+    items:
+      type: string
+    description: TBD
+  _attributeGroups:
+    type: array
+    items:
+      type: object
+    description: TBD (WorkPackageFormAttributeGroup)
+  lockVersion:
+    $ref: './schema_property_model.yml'
+  id:
+    $ref: './schema_property_model.yml'
+  subject:
+    $ref: './schema_property_model.yml'
+  description:
+    $ref: './schema_property_model.yml'
+  duration:
+    $ref: './schema_property_model.yml'
+  scheduleManually:
+    $ref: './schema_property_model.yml'
+  ignoreNonWorkingDays:
+    $ref: './schema_property_model.yml'
+  startDate:
+    $ref: './schema_property_model.yml'
+  dueDate:
+    $ref: './schema_property_model.yml'
+  derivedStartDate:
+    $ref: './schema_property_model.yml'
+  derivedDueDate:
+    $ref: './schema_property_model.yml'
+  estimatedTime:
+    $ref: './schema_property_model.yml'
+  derivedEstimatedTime:
+    $ref: './schema_property_model.yml'
+  remainingTime:
+    $ref: './schema_property_model.yml'
+  derivedRemainingTime:
+    $ref: './schema_property_model.yml'
+  percentageDone:
+    $ref: './schema_property_model.yml'
+  derivedPercentageDone:
+    $ref: './schema_property_model.yml'
+  readonly:
+    $ref: './schema_property_model.yml'
+  createdAt:
+    $ref: './schema_property_model.yml'
+  updatedAt:
+    $ref: './schema_property_model.yml'
+  author:
+    $ref: './schema_property_model.yml'
+  project:
+    $ref: './schema_property_model.yml'
+  parent:
+    $ref: './schema_property_model.yml'
+  assignee:
+    $ref: './schema_property_model.yml'
+  responsible:
+    $ref: './schema_property_model.yml'
+  type:
+    $ref: './schema_property_model.yml'
+  status:
+    $ref: './schema_property_model.yml'
+  category:
+    $ref: './schema_property_model.yml'
+  version:
+    $ref: './schema_property_model.yml'
+  priority:
+    $ref: './schema_property_model.yml'
+  _links:
+    type: object
+    properties:
+      self:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              This work package schema
+              
+              **Resource**: Schema