[#57016] updated status API specification

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

@@ -1,72 +1,89 @@
-# Example: Status collection
----
+description: |-
+  A standard, unpaginated collection of statuses.
 value:
+  _type: Collection
+  count: 6
+  total: 6
   _embedded:
     elements:
-      - _links:
-          self:
-            href: "/api/v3/statuses/1"
-        _type: Status
-        defaultDoneRatio: 0
+      - _type: Status
         id: 1
+        name: New
         isClosed: false
+        color: '#3997AD'
         isDefault: true
-        name: New
+        isReadonly: false
+        excludedFromTotals: false
+        defaultDoneRatio: 0
         position: 1
-      - _links:
+        _links:
           self:
-            href: "/api/v3/statuses/3"
-        _type: Status
-        defaultDoneRatio: 75
+            href: '/api/v3/statuses/1'
+      - _type: Status
         id: 3
+        name: Resolved
         isClosed: false
+        color: '#93D2AE'
         isDefault: false
         isReadonly: false
-        name: Resolved
+        excludedFromTotals: false
+        defaultDoneRatio: 75
         position: 3
-      - _links:
+        _links:
           self:
-            href: "/api/v3/statuses/4"
-        _type: Status
-        defaultDoneRatio: 25
+            href: '/api/v3/statuses/3'
+      - _type: Status
         id: 4
+        name: Feedback
         isClosed: false
+        color: '#A96FFE'
         isDefault: false
-        name: Feedback
+        isReadonly: false
+        excludedFromTotals: false
+        defaultDoneRatio: 25
         position: 4
-      - _links:
+        _links:
           self:
-            href: "/api/v3/statuses/5"
-        _type: Status
-        defaultDoneRatio: 100
+            href: '/api/v3/statuses/4'
+      - _type: Status
         id: 5
+        name: Closed
         isClosed: true
+        color: '#DF6DA1'
         isDefault: false
-        name: Closed
+        isReadonly: false
+        excludedFromTotals: false
+        defaultDoneRatio: 100
         position: 5
-      - _links:
+        _links:
           self:
-            href: "/api/v3/statuses/6"
-        _type: Status
-        defaultDoneRatio: 100
+            href: '/api/v3/statuses/5'
+      - _type: Status
         id: 6
+        name: Rejected
         isClosed: true
+        color: '#D32937'
         isDefault: false
-        name: Rejected
+        isReadonly: true
+        excludedFromTotals: true
+        defaultDoneRatio: 100
         position: 6
-      - _links:
+        _links:
           self:
-            href: "/api/v3/statuses/2"
-        _type: Status
-        defaultDoneRatio: 50
+            href: '/api/v3/statuses/6'
+      - _type: Status
         id: 2
+        name: In Progress
         isClosed: false
+        color: '#3852C6'
         isDefault: false
-        name: In Progress
+        isReadonly: false
+        excludedFromTotals: false
+        defaultDoneRatio: 50
         position: 3
+        _links:
+          self:
+            href: '/api/v3/statuses/2'
   _links:
     self:
-      href: "/api/v3/statuses"
-  _type: Collection
-  count: 6
-  total: 6
+      href: '/api/v3/statuses'

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

@@ -0,0 +1,16 @@
+description: A standard status resource response.
+value:
+  _type: Status
+  id: 13
+  name: Waiting for Darth-approval
+  isClosed: false
+  color: '#FE005D'
+  isDefault: false
+  isReadonly: false
+  excludedFromTotals: false
+  defaultDoneRatio: 66
+  position: 4
+  _links:
+    self:
+      href: '/api/v3/statuses/13'
+      title: Waiting for Darth-approval

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

@@ -4,21 +4,8 @@ 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 links collection
-
-                  **Resource**: StatusCollectionModel
       _embedded:
         type: object
         required:

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

@@ -9,52 +9,45 @@ properties:
   id:
     type: integer
     description: Status id
-    readOnly: true
     minimum: 1
   name:
     type: string
     description: Status name
-    readOnly: true
-  position:
-    type: integer
-    description: Sort index of the status
-    readOnly: true
-  isDefault:
-    type: boolean
-    readOnly: true
   isClosed:
     type: boolean
-    description: are tickets of this status considered closed?
-    readOnly: true
+    description: Indicates, whether work package of this status are considered closed
+  color:
+    type: string
+    format: hex-code
+    description: The color of the status
+  isDefault:
+    type: boolean
+    description: True, if this status is the default status for new work packages
   isReadonly:
     type: boolean
-    description: are tickets of this status read only?
-    readOnly: true
+    description: Indicates, whether work package of this status are readonly
+  excludedFromTotals:
+    type: boolean
+    description: |-
+      Indicates, whether work package of this status are excluded from totals of `Work`, `Remaining work`, and
+      `% Complete` in a hierarchy.
   defaultDoneRatio:
     type: integer
     description: The percentageDone being applied when changing to this status
+    minimum: 0
     maximum: 100
+  position:
+    type: integer
+    description: Sort index of the status
   _links:
     type: object
     required:
-    - self
+      - self
     properties:
       self:
         allOf:
-        - "$ref": "./link.yml"
-        - description: |-
-            This status
-
-            **Resource**: Status
-          readOnly: true
-example:
-  _links:
-    self:
-      href: "/api/v3/statuses/1"
-  _type: Status
-  id: 1
-  name: New
-  position: 1
-  isDefault: true
-  isClosed: false
-  defaultDoneRatio: 0
+          - $ref: './link.yml'
+          - description: |-
+              This status
+
+              **Resource**: Status

docs/api/apiv3/openapi-spec.yml

@@ -527,6 +527,10 @@ components:
       $ref: "./components/examples/relation_response.yml"
     RelationUpdateRequest:
       $ref: "./components/examples/relation_update_request.yml"
+    StatusCollection:
+      $ref: "./components/examples/status_collection.yml"
+    StatusResponse:
+      $ref: "./components/examples/status_response.yml"
     StorageNextcloudResponse:
       $ref: "./components/examples/storage-nextcloud-response.yml"
     StorageNextcloudResponseForCreation:
@@ -537,16 +541,14 @@ components:
       $ref: "./components/examples/storage-one-drive-incomplete-response.yml"
     StorageOneDriveResponse:
       $ref: "./components/examples/storage-one-drive-response.yml"
+    StoragesSimpleCollectionModel:
+      $ref: "./components/examples/storages-simple-collection-response.yml"
     QueriesModel:
       $ref: "./components/examples/queries.yml"
     QueryModel:
       $ref: "./components/examples/query.yml"
     QuerySchemaModel:
       $ref: "./components/examples/query_schema.yml"
-    StatusCollection:
-      $ref: "./components/examples/status_collection.yml"
-    StoragesSimpleCollectionModel:
-      $ref: "./components/examples/storages-simple-collection-response.yml"
     UserResponse:
       $ref: "./components/examples/user-response.yml"
     ValuesPropertyStartDateSchema:

docs/api/apiv3/paths/status.yml

@@ -1,53 +1,54 @@
 # /api/v3/statuses/{id}
 ---
 get:
+  summary: Get a work package status
+  operationId: get_status
+  tags:
+    - Statuses
+  description: |-
+    Returns a work package status by its unique identifier.
   parameters:
-  - description: Status id
-    example: '1'
-    in: path
-    name: id
-    required: true
-    schema:
-      type: integer
+    - name: id
+      description: Status id
+      in: path
+      required: true
+      schema:
+        type: integer
+      example: '1'
   responses:
     '200':
+      description: OK
       content:
         application/hal+json:
           examples:
             response:
-              value:
-                _links:
-                  self:
-                    href: "/api/v3/statuses/1"
-                _type: Status
-                defaultDoneRatio: 0
-                id: 1
-                isClosed: false
-                isDefault: true
-                name: New
-                position: 1
+              $ref: '../components/examples/status_response.yml'
           schema:
-            "$ref": "../components/schemas/status_model.yml"
-      description: OK
-      headers: {}
+            $ref: '../components/schemas/status_model.yml'
     '403':
+      description: |-
+        Returned if the client does not have sufficient permissions.
+
+        **Required permission:** view work package (on any project)
       content:
         application/hal+json:
           schema:
-            $ref: "../components/schemas/error_response.yml"
+            $ref: '../components/schemas/error_response.yml'
           examples:
             response:
               value:
                 _type: Error
                 errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                 message: You are not allowed to see this status.
-      description: |-
-        Returned if the client does not have sufficient permissions.
-
-        **Required permission:** view work package (on any project)
-      headers: {}
-  tags:
-  - Statuses
-  description: ''
-  operationId: View_Status
-  summary: View Status
+    '404':
+      description: Returned if the status does not exist.
+      content:
+        application/hal+json:
+          schema:
+            $ref: '../components/schemas/error_response.yml'
+          examples:
+            response:
+              value:
+                _type: Error
+                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
+                message: The requested resource could not be found.