chore(oas): [16/n] improve oas schemas (#9272)

- Improve OAS schemas [16/n]
- fixes and improvements to docs-generator tool

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

@@ -58,19 +58,19 @@
  *   thumbnail:
  *     type: string
  *     title: thumbnail
- *     description: The item's thumbnail.
+ *     description: The URL of the item's thumbnail.
  *   variant:
- *     $ref: "#/components/schemas/BaseProductVariant"
+ *     $ref: "#/components/schemas/AdminProductVariant"
  *   variant_id:
  *     type: string
  *     title: variant_id
- *     description: The item's variant id.
+ *     description: The ID of the associated variant.
  *   product:
  *     $ref: "#/components/schemas/BaseProduct"
  *   product_id:
  *     type: string
  *     title: product_id
- *     description: The item's product id.
+ *     description: The ID of the associated product.
  *   product_title:
  *     type: string
  *     title: product_title
@@ -90,7 +90,7 @@
  *   product_collection:
  *     type: string
  *     title: product_collection
- *     description: The item's product collection.
+ *     description: The ID of the collection the item's product belongs to.
  *   product_handle:
  *     type: string
  *     title: product_handle
@@ -98,7 +98,7 @@
  *   variant_sku:
  *     type: string
  *     title: variant_sku
- *     description: The item's variant sku.
+ *     description: The item's variant SKU.
  *   variant_barcode:
  *     type: string
  *     title: variant_barcode
@@ -109,23 +109,25 @@
  *     description: The item's variant title.
  *   variant_option_values:
  *     type: object
- *     description: The item's variant option values.
+ *     description: The values of the item variant's options.
+ *     example:
+ *       Color: Blue
  *   requires_shipping:
  *     type: boolean
  *     title: requires_shipping
- *     description: The item's requires shipping.
+ *     description: Whether the item requires shipping.
  *   is_discountable:
  *     type: boolean
  *     title: is_discountable
- *     description: The item's is discountable.
+ *     description: Whether the item is discountable.
  *   is_tax_inclusive:
  *     type: boolean
  *     title: is_tax_inclusive
- *     description: The item's is tax inclusive.
+ *     description: Whether the item is tax inclusive.
  *   compare_at_unit_price:
  *     type: number
  *     title: compare_at_unit_price
- *     description: The item's compare at unit price.
+ *     description: The original price of the item before a promotion or sale.
  *   unit_price:
  *     type: number
  *     title: unit_price
@@ -150,67 +152,66 @@
  *     type: string
  *     format: date-time
  *     title: created_at
- *     description: The item's created at.
+ *     description: The date the item was created.
  *   updated_at:
  *     type: string
  *     format: date-time
  *     title: updated_at
- *     description: The item's updated at.
+ *     description: The date the item was updated.
  *   metadata:
  *     type: object
- *     description: The item's metadata.
+ *     description: The item's metadata, can hold custom key-value pairs.
  *   original_total:
  *     type: number
  *     title: original_total
- *     description: The item's original total.
+ *     description: The item's total including taxes, excluding promotions.
  *   original_subtotal:
  *     type: number
  *     title: original_subtotal
- *     description: The item's original subtotal.
+ *     description: The item's total excluding taxes, including promotions.
  *   original_tax_total:
  *     type: number
  *     title: original_tax_total
- *     description: The item's original tax total.
+ *     description: The total taxes of the item, excluding promotions.
  *   item_total:
  *     type: number
  *     title: item_total
- *     description: The item's item total.
+ *     description: The total taxes of the item, including promotions.
  *   item_subtotal:
  *     type: number
  *     title: item_subtotal
- *     description: The item's item subtotal.
+ *     description: The item's total excluding taxes, including promotions.
  *   item_tax_total:
  *     type: number
  *     title: item_tax_total
- *     description: The item's item tax total.
+ *     description: The total taxes of the item, including promotions.
  *   total:
  *     type: number
  *     title: total
- *     description: The item's total.
+ *     description: The item's total, including taxes and promotions.
  *   subtotal:
  *     type: number
  *     title: subtotal
- *     description: The item's subtotal.
+ *     description: The item's subtotal excluding taxes, including promotions.
  *   tax_total:
  *     type: number
  *     title: tax_total
- *     description: The item's tax total.
+ *     description: The tax total of the item including promotions.
  *   discount_total:
  *     type: number
  *     title: discount_total
- *     description: The item's discount total.
+ *     description: The total discount amount of the item.
  *   discount_tax_total:
  *     type: number
  *     title: discount_tax_total
- *     description: The item's discount tax total.
+ *     description: The total taxes applied on the discounted amount.
  *   refundable_total:
  *     type: number
  *     title: refundable_total
- *     description: The item's refundable total.
+ *     description: The total refundable amount of the item's total.
  *   refundable_total_per_unit:
  *     type: number
  *     title: refundable_total_per_unit
- *     description: The item's refundable total per unit.
+ *     description: The total refundable amount of the item's total for a single quantity.
  * 
 */
-