oas: [6/n] improve oas schemas (#9122)

Improve oas schemas [6/n]

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminNotificationListResponse
  * type: object
- * description: SUMMARY
+ * description: The paginated list of notifications.
  * x-schemaName: AdminNotificationListResponse
  * required:
  *   - limit
@@ -12,18 +12,18 @@
  *   limit:
  *     type: number
  *     title: limit
- *     description: The notification's limit.
+ *     description: The maximum number of items returned.
  *   offset:
  *     type: number
  *     title: offset
- *     description: The notification's offset.
+ *     description: The number of items skipped before retrieving the returned items.
  *   count:
  *     type: number
  *     title: count
- *     description: The notification's count.
+ *     description: The total count of items.
  *   notifications:
  *     type: array
- *     description: The notification's notifications.
+ *     description: The list of notifications.
  *     items:
  *       $ref: "#/components/schemas/AdminNotification"
  * 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminNotificationResponse
  * type: object
- * description: SUMMARY
+ * description: The notification's details.
  * x-schemaName: AdminNotificationResponse
  * required:
  *   - notification

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

@@ -72,19 +72,19 @@
  *   region_id:
  *     type: string
  *     title: region_id
- *     description: The order's region id.
+ *     description: The ID of the region associated with the order.
  *   customer_id:
  *     type: string
  *     title: customer_id
- *     description: The order's customer id.
+ *     description: The ID of the customer that placed the order.
  *   sales_channel_id:
  *     type: string
  *     title: sales_channel_id
- *     description: The order's sales channel id.
+ *     description: The ID of the sales channel the order is placed in.
  *   email:
  *     type: string
  *     title: email
- *     description: The order's email.
+ *     description: The email of the customer that placed the order.
  *     format: email
  *   currency_code:
  *     type: string
@@ -93,7 +93,7 @@
  *   display_id:
  *     type: number
  *     title: display_id
- *     description: The order's display id.
+ *     description: The order's display ID.
  *   items:
  *     type: array
  *     description: The order's items.
@@ -139,105 +139,105 @@
  *     $ref: "#/components/schemas/BaseOrderSummary"
  *   metadata:
  *     type: object
- *     description: The order's metadata.
+ *     description: The order's metadata, can hold custom key-value pairs.
  *   created_at:
  *     type: string
  *     format: date-time
  *     title: created_at
- *     description: The order's created at.
+ *     description: The date the order was created.
  *   updated_at:
  *     type: string
  *     format: date-time
  *     title: updated_at
- *     description: The order's updated at.
+ *     description: The date the order was updated.
  *   original_item_total:
  *     type: number
  *     title: original_item_total
- *     description: The order's original item total.
+ *     description: The total of the order's items including taxes, excluding promotions.
  *   original_item_subtotal:
  *     type: number
  *     title: original_item_subtotal
- *     description: The order's original item subtotal.
+ *     description: The total of the order's items excluding taxes, including promotions.
  *   original_item_tax_total:
  *     type: number
  *     title: original_item_tax_total
- *     description: The order's original item tax total.
+ *     description: The tax total of the order's items excluding promotions.
  *   item_total:
  *     type: number
  *     title: item_total
- *     description: The order's item total.
+ *     description: The total of the order's items including taxes and promotions.
  *   item_subtotal:
  *     type: number
  *     title: item_subtotal
- *     description: The order's item subtotal.
+ *     description: The total of the order's items excluding taxes, including promotions.
  *   item_tax_total:
  *     type: number
  *     title: item_tax_total
- *     description: The order's item tax total.
+ *     description: The tax total of the order's items including promotions.
  *   original_total:
  *     type: number
  *     title: original_total
- *     description: The order's original total.
+ *     description: The order's total excluding promotions, including taxes.
  *   original_subtotal:
  *     type: number
  *     title: original_subtotal
- *     description: The order's original subtotal.
+ *     description: The order's total excluding taxes, including promotions.
  *   original_tax_total:
  *     type: number
  *     title: original_tax_total
- *     description: The order's original tax total.
+ *     description: The order's tax total, excluding promotions.
  *   total:
  *     type: number
  *     title: total
- *     description: The order's total.
+ *     description: The order's total including taxes and promotions.
  *   subtotal:
  *     type: number
  *     title: subtotal
- *     description: The order's subtotal.
+ *     description: The order's total excluding taxes, including promotions.
  *   tax_total:
  *     type: number
  *     title: tax_total
- *     description: The order's tax total.
+ *     description: The order's tax total including promotions.
  *   discount_total:
  *     type: number
  *     title: discount_total
- *     description: The order's discount total.
+ *     description: The order's discount or promotions total.
  *   discount_tax_total:
  *     type: number
  *     title: discount_tax_total
- *     description: The order's discount tax total.
+ *     description: The tax total of order's discount or promotion.
  *   gift_card_total:
  *     type: number
  *     title: gift_card_total
  *     description: The order's gift card total.
  *   gift_card_tax_total:
  *     type: number
  *     title: gift_card_tax_total
- *     description: The order's gift card tax total.
+ *     description: The tax total of the order's gift card.
  *   shipping_total:
  *     type: number
  *     title: shipping_total
- *     description: The order's shipping total.
+ *     description: The order's shipping total including taxes and promotions.
  *   shipping_subtotal:
  *     type: number
  *     title: shipping_subtotal
- *     description: The order's shipping subtotal.
+ *     description: The order's shipping total excluding taxes, including promotions.
  *   shipping_tax_total:
  *     type: number
  *     title: shipping_tax_total
- *     description: The order's shipping tax total.
+ *     description: The tax total of the order's shipping.
  *   original_shipping_total:
  *     type: number
  *     title: original_shipping_total
- *     description: The order's original shipping total.
+ *     description: The order's shipping total including taxes, excluding promotions.
  *   original_shipping_subtotal:
  *     type: number
  *     title: original_shipping_subtotal
- *     description: The order's original shipping subtotal.
+ *     description: The order's shipping total excluding taxes, including promotions.
  *   original_shipping_tax_total:
  *     type: number
  *     title: original_shipping_tax_total
- *     description: The order's original shipping tax total.
+ *     description: The tax total of the order's shipping excluding promotions.
  * 
 */
 

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

@@ -1,77 +1,78 @@
 /**
  * @schema AdminOrderAddress
  * type: object
- * description: The order's billing address.
+ * description: An order address.
  * x-schemaName: AdminOrderAddress
  * required:
  *   - id
  *   - metadata
  *   - created_at
  *   - updated_at
  * properties:
- *   country:
- *     $ref: "#/components/schemas/AdminRegionCountry"
  *   id:
  *     type: string
  *     title: id
- *     description: The billing address's ID.
+ *     description: The address's ID.
  *   customer_id:
  *     type: string
  *     title: customer_id
- *     description: The billing address's customer id.
+ *     description: The ID of the customer this address belongs to.
  *   first_name:
  *     type: string
  *     title: first_name
- *     description: The billing address's first name.
+ *     description: The address's first name.
  *   last_name:
  *     type: string
  *     title: last_name
- *     description: The billing address's last name.
+ *     description: The address's last name.
  *   phone:
  *     type: string
  *     title: phone
- *     description: The billing address's phone.
+ *     description: The address's phone.
  *   company:
  *     type: string
  *     title: company
- *     description: The billing address's company.
+ *     description: The address's company.
  *   address_1:
  *     type: string
  *     title: address_1
- *     description: The billing address's address 1.
+ *     description: The address's first line.
  *   address_2:
  *     type: string
  *     title: address_2
- *     description: The billing address's address 2.
+ *     description: The address's second line.
  *   city:
  *     type: string
  *     title: city
- *     description: The billing address's city.
+ *     description: The address's city.
  *   country_code:
  *     type: string
  *     title: country_code
- *     description: The billing address's country code.
+ *     description: The address's country code.
+ *     example: us
+ *   country:
+ *     $ref: "#/components/schemas/AdminRegionCountry"
  *   province:
  *     type: string
  *     title: province
- *     description: The billing address's province.
+ *     description: The address's province.
  *   postal_code:
  *     type: string
  *     title: postal_code
- *     description: The billing address's postal code.
+ *     description: The address's postal code.
  *   metadata:
  *     type: object
- *     description: The billing address's metadata.
+ *     description: The address's metadata, can hold custom key-value pairs.
  *   created_at:
  *     type: string
  *     format: date-time
  *     title: created_at
- *     description: The billing address's created at.
+ *     description: The date the address was created.
  *   updated_at:
  *     type: string
  *     format: date-time
  *     title: updated_at
- *     description: The billing address's updated at.
+ *     description: The date the address was updated.
  * 
 */
 

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

@@ -1,14 +1,14 @@
 /**
  * @schema AdminOrderChangesResponse
  * type: object
- * description: SUMMARY
+ * description: The details of an order's changes.
  * x-schemaName: AdminOrderChangesResponse
  * required:
  *   - order_changes
  * properties:
  *   order_changes:
  *     type: array
- *     description: The order's order changes.
+ *     description: An order's changes.
  *     items:
  *       $ref: "#/components/schemas/BaseOrderChange"
  * 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminOrderEditPreviewResponse
  * type: object
- * description: SUMMARY
+ * description: The preview of an order edit.
  * x-schemaName: AdminOrderEditPreviewResponse
  * required:
  *   - order_preview

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminOrderEditResponse
  * type: object
- * description: SUMMARY
+ * description: An order edit's details.
  * x-schemaName: AdminOrderEditResponse
  * required:
  *   - order_change