chore(docs): Updated API Reference (v2) (#9148)

Automated changes by [create-pull-request](https://github.com/peter-evans/create-pull-request) GitHub action

Co-authored-by: Oli Juhl <59018053+olivermrbl@users.noreply.github.com>

www/apps/api-reference/specs/admin/components/schemas/AdminCreatePromotionRule.yaml

@@ -1,5 +1,5 @@
 type: object
-description: The rule's rules.
+description: The promotion rule's details.
 x-schemaName: AdminCreatePromotionRule
 required:
   - operator
@@ -8,7 +8,10 @@ required:
 properties:
   operator:
     type: string
-    description: The rule's operator.
+    description: >-
+      The operator used to check whether the buy rule applies on a cart. For
+      example, `eq` means that the cart's value for the specified attribute must
+      match the specified value.
     enum:
       - gt
       - lt
@@ -24,15 +27,20 @@ properties:
   attribute:
     type: string
     title: attribute
-    description: The rule's attribute.
+    description: >-
+      The attribute to compare against when checking whether a promotion can be
+      applied on a cart.
+    example: item.product.id
   values:
     oneOf:
       - type: string
         title: values
-        description: The rule's values.
+        description: The attribute's value.
+        example: prod_123
       - type: array
-        description: The rule's values.
+        description: The allowed attribute values.
         items:
           type: string
           title: values
-          description: The value's values.
+          description: An attribute value.
+          example: prod_123