Adjust documentation for supported live message conditions

Co-authored-by: Stanchev Aleksandar <aleksandar.stanchev@bosch.io>
Signed-off-by: David Schwilk <david.schwilk@bosch.io>

documentation/src/main/resources/openapi/README.md

@@ -16,9 +16,6 @@ To extend or update the OpenAPI of Ditto you can add or change the files in the
 // go to sources
 $ cd sources
 
-// only v2
-$ npm run build-v2
-
-// both
+// run build
 $ npm run build
 ```

documentation/src/main/resources/openapi/ditto-api-2.yml

@@ -4211,6 +4211,7 @@ paths:
         - $ref: '#/components/parameters/MessageSubjectPathParam'
         - $ref: '#/components/parameters/MessageTimeoutParam'
         - $ref: '#/components/parameters/LiveMessageRequestedAcksParam'
+        - $ref: '#/components/parameters/ConditionParam'
       responses:
         '202':
           description: The message was sent but not necessarily received by the thing (fire and forget).
@@ -4253,6 +4254,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/AdvancedError'
+        '412':
+          $ref: '#/components/responses/PreconditionFailed'
         '413':
           $ref: '#/components/responses/MessageTooLarge'
         '424':
@@ -4290,6 +4293,7 @@ paths:
         - $ref: '#/components/parameters/MessageSubjectPathParam'
         - $ref: '#/components/parameters/MessageTimeoutParam'
         - $ref: '#/components/parameters/LiveMessageRequestedAcksParam'
+        - $ref: '#/components/parameters/ConditionParam'
       responses:
         '202':
           description: The message was sent (fire and forget).
@@ -4332,6 +4336,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/AdvancedError'
+        '412':
+          $ref: '#/components/responses/PreconditionFailed'
         '413':
           $ref: '#/components/responses/MessageTooLarge'
         '424':
@@ -4371,6 +4377,7 @@ paths:
         - $ref: '#/components/parameters/MessageSubjectPathParam'
         - $ref: '#/components/parameters/MessageTimeoutParam'
         - $ref: '#/components/parameters/LiveMessageRequestedAcksParam'
+        - $ref: '#/components/parameters/ConditionParam'
       responses:
         '202':
           description: |-
@@ -4415,6 +4422,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/AdvancedError'
+        '412':
+          $ref: '#/components/responses/PreconditionFailed'
         '413':
           $ref: '#/components/responses/MessageTooLarge'
         '424':
@@ -4454,6 +4463,7 @@ paths:
         - $ref: '#/components/parameters/MessageSubjectPathParam'
         - $ref: '#/components/parameters/MessageTimeoutParam'
         - $ref: '#/components/parameters/LiveMessageRequestedAcksParam'
+        - $ref: '#/components/parameters/ConditionParam'
       responses:
         '202':
           description: The message was sent (fire and forget).
@@ -4496,6 +4506,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/AdvancedError'
+        '412':
+          $ref: '#/components/responses/PreconditionFailed'
         '413':
           $ref: '#/components/responses/MessageTooLarge'
         '424':
@@ -7179,7 +7191,7 @@ components:
       name: condition
       in: query
       description: |-
-        Defines that the request should only be applied to a thing if the given condition is met. The condition can be specified using RQL syntax. 
+        Defines that the request should only be processed if the given condition is met. The condition can be specified using RQL syntax. 
         #### Examples
         E.g. if the temperature is not 23.9 update it to 23.9:
         * ```PUT /api/2/things/{thingId}/features/temperature/properties/value?condition=ne(features/temperature/properties/value,23.9)```
@@ -8095,7 +8107,7 @@ components:
         randomizationInterval:
           type: string
           default: 5m
-          description: 'Interval in which the announcement can be sent earlier in effort to prevent announcement peaks. If omitted, the default value will be applied. If set to minimum, no randomization will be applied.'
+          description: 'Interval in which the announcement can be sent earlier than the configured `beforeExpiry`. The actual point in time when the announcement will be sent is `beforeExpire` plus a randomly chosen time within the `randomizationInterval`. E.g assuming `beforeExpiry` is set to 5m and `randomizationInterval` is set to 1m, the announcements will be sent between 5 and 6 minutes before the subject expires. If omitted, the default value will be applied. If set to minimum, no randomization will be applied.'
       example:
         beforeExpiry: 5m
         whenDeleted: true

documentation/src/main/resources/openapi/sources/parameters/conditionParam.yml

@@ -11,7 +11,7 @@
 name: condition
 in: query
 description: >-
-  Defines that the request should only be applied to a thing if the given condition is met.
+  Defines that the request should only be processed if the given condition is met.
   The condition can be specified using RQL syntax. 
 
   #### Examples

documentation/src/main/resources/openapi/sources/paths/messages/feature-inbox-message.yml

@@ -40,6 +40,7 @@ post:
     - $ref: '../../parameters/messageSubjectPathParam.yml'
     - $ref: '../../parameters/messageTimeoutParam.yml'
     - $ref: '../../parameters/liveMessageRequestedAcksParam.yml'
+    - $ref: '../../parameters/conditionParam.yml'
   responses:
     '202':
       description: |-
@@ -84,6 +85,8 @@ post:
         application/json:
           schema:
             $ref: '../../schemas/errors/advancedError.yml'
+    '412':
+      $ref: '../../responses/preconditionFailed.yml'
     '413':
       $ref: '../../responses/messageTooLarge.yml'
     '424':

documentation/src/main/resources/openapi/sources/paths/messages/feature-outbox-message.yml

@@ -40,6 +40,7 @@ post:
     - $ref: '../../parameters/messageSubjectPathParam.yml'
     - $ref: '../../parameters/messageTimeoutParam.yml'
     - $ref: '../../parameters/liveMessageRequestedAcksParam.yml'
+    - $ref: '../../parameters/conditionParam.yml'
   responses:
     '202':
       description: The message was sent (fire and forget).
@@ -82,6 +83,8 @@ post:
         application/json:
           schema:
             $ref: '../../schemas/errors/advancedError.yml'
+    '412':
+      $ref: '../../responses/preconditionFailed.yml'
     '413':
       $ref: '../../responses/messageTooLarge.yml'
     '424':

documentation/src/main/resources/openapi/sources/paths/messages/inbox-message.yml

@@ -51,6 +51,7 @@ post:
     - $ref: '../../parameters/messageSubjectPathParam.yml'
     - $ref: '../../parameters/messageTimeoutParam.yml'
     - $ref: '../../parameters/liveMessageRequestedAcksParam.yml'
+    - $ref: '../../parameters/conditionParam.yml'
   responses:
     '202':
       description: |-
@@ -94,6 +95,8 @@ post:
         application/json:
           schema:
             $ref: '../../schemas/errors/advancedError.yml'
+    '412':
+      $ref: '../../responses/preconditionFailed.yml'
     '413':
       $ref: '../../responses/messageTooLarge.yml'
     '424':

documentation/src/main/resources/openapi/sources/paths/messages/outbox-message.yml

@@ -38,6 +38,7 @@ post:
     - $ref: '../../parameters/messageSubjectPathParam.yml'
     - $ref: '../../parameters/messageTimeoutParam.yml'
     - $ref: '../../parameters/liveMessageRequestedAcksParam.yml'
+    - $ref: '../../parameters/conditionParam.yml'
   responses:
     '202':
       description: The message was sent (fire and forget).
@@ -80,6 +81,8 @@ post:
         application/json:
           schema:
             $ref: '../../schemas/errors/advancedError.yml'
+    '412':
+      $ref: '../../responses/preconditionFailed.yml'
     '413':
       $ref: '../../responses/messageTooLarge.yml'
     '424':

documentation/src/main/resources/pages/ditto/basic-conditional-requests.md

@@ -12,8 +12,8 @@ It is possible to combine both headers within one request. If you use both heade
 
 ## Defining conditions
 
-Ditto supports retrieving, modifying, and deleting things based on specific conditions of the current persisted twin state.
-Conditions are not intended to be used for message dispatching.
+Ditto supports retrieving, modifying, deleting and sending messages to/from things based on specific conditions of the 
+current persisted twin state.
 For example, if you want to update the value of an attribute, but only if the current attribute value is not already 42,
 you can specify a condition: