chore(oas): [19/n] improve oas schemas (#9317)

- Improve OAS schemas [19/n]
- docs-generator: combine `Date | string` type to just `Date`.

www/utils/generated/oas-output/schemas/OrderChange.ts

@@ -1,7 +1,7 @@
 /**
  * @schema OrderChange
  * type: object
- * description: The order preview's order change.
+ * description: The order change's details.
  * x-schemaName: OrderChange
  * required:
  *   - id
@@ -36,10 +36,10 @@
  *   version:
  *     type: number
  *     title: version
- *     description: The order change's version.
+ *     description: The order change's version. This will be the order's version when the change is applied.
  *   change_type:
  *     type: string
- *     description: The order change's change type.
+ *     description: The order change's type.
  *     enum:
  *       - return
  *       - exchange
@@ -48,19 +48,19 @@
  *   order_id:
  *     type: string
  *     title: order_id
- *     description: The order change's order id.
+ *     description: The ID of the order this change applies on.
  *   return_id:
  *     type: string
  *     title: return_id
- *     description: The order change's return id.
+ *     description: The ID of the associated return.
  *   exchange_id:
  *     type: string
  *     title: exchange_id
- *     description: The order change's exchange id.
+ *     description: The ID of the associated exchange.
  *   claim_id:
  *     type: string
  *     title: claim_id
- *     description: The order change's claim id.
+ *     description: The ID of the associated claim.
  *   order:
  *     $ref: "#/components/schemas/Order"
  *   return_order:
@@ -76,77 +76,66 @@
  *       $ref: "#/components/schemas/OrderChangeAction"
  *   status:
  *     type: string
- *     title: status
  *     description: The order change's status.
+ *     enum:
+ *       - canceled
+ *       - requested
+ *       - pending
+ *       - confirmed
+ *       - declined
  *   requested_by:
  *     type: string
  *     title: requested_by
- *     description: The order change's requested by.
+ *     description: The ID of the user that requested the change.
  *   requested_at:
- *     oneOf:
- *       - type: string
- *         title: requested_at
- *         description: The order change's requested at.
- *       - type: string
- *         title: requested_at
- *         description: The order change's requested at.
- *         format: date-time
+ *     type: string
+ *     title: requested_at
+ *     description: The date the order change was requested.
+ *     format: date-time
  *   confirmed_by:
  *     type: string
  *     title: confirmed_by
- *     description: The order change's confirmed by.
+ *     description: The ID of the user that confirmed the order change.
  *   confirmed_at:
- *     oneOf:
- *       - type: string
- *         title: confirmed_at
- *         description: The order change's confirmed at.
- *       - type: string
- *         title: confirmed_at
- *         description: The order change's confirmed at.
- *         format: date-time
+ *     type: string
+ *     title: confirmed_at
+ *     description: The date the order change was confirmed.
+ *     format: date-time
  *   declined_by:
  *     type: string
  *     title: declined_by
- *     description: The order change's declined by.
+ *     description: The ID of the user that declined the order change.
  *   declined_reason:
  *     type: string
  *     title: declined_reason
- *     description: The order change's declined reason.
+ *     description: The reason the order change was declined.
  *   metadata:
  *     type: object
- *     description: The order change's metadata.
+ *     description: The order change's metadata, can hold custom key-value pairs.
  *   declined_at:
- *     oneOf:
- *       - type: string
- *         title: declined_at
- *         description: The order change's declined at.
- *       - type: string
- *         title: declined_at
- *         description: The order change's declined at.
- *         format: date-time
+ *     type: string
+ *     title: declined_at
+ *     description: The date the order change was declined.
+ *     format: date-time
  *   canceled_by:
  *     type: string
  *     title: canceled_by
- *     description: The order change's canceled by.
+ *     description: The ID of the user that canceled the order change.
  *   canceled_at:
- *     oneOf:
- *       - type: string
- *         title: canceled_at
- *         description: The order change's canceled at.
- *       - type: string
- *         title: canceled_at
- *         description: The order change's canceled at.
- *         format: date-time
+ *     type: string
+ *     title: canceled_at
+ *     description: The date the order change was canceled.
+ *     format: date-time
  *   created_at:
  *     type: string
  *     format: date-time
  *     title: created_at
- *     description: The order change's created at.
+ *     description: The date the order change was created.
  *   updated_at:
  *     type: string
  *     format: date-time
  *     title: updated_at
- *     description: The order change's updated at.
+ *     description: The date the order change was updated.
  * 
 */