chore(oas): [21/21] improve oas schemas (#9339)

* improve oas

* more improvements

* add missing descriptions

---------

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

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

@@ -1,7 +1,7 @@
 /**
  * @schema StoreShippingOption
  * type: object
- * description: The shipping option's shipping options.
+ * description: The shipping option's details.
  * x-schemaName: StoreShippingOption
  * required:
  *   - id
@@ -28,30 +28,30 @@
  *     description: The shipping option's name.
  *   price_type:
  *     type: string
- *     description: The shipping option's price type.
+ *     description: The shipping option's price type. If it's `flat`, the price is fixed and is set in the `prices` property. If it's `calculated`, the price is calculated on checkout by the associated fulfillment provider.
  *     enum:
  *       - flat
  *       - calculated
  *   service_zone_id:
  *     type: string
  *     title: service_zone_id
- *     description: The shipping option's service zone id.
+ *     description: The ID of the service zone the shipping option belongs to.
  *   provider_id:
  *     type: string
  *     title: provider_id
- *     description: The shipping option's provider id.
+ *     description: The ID of the fulfillment provider handling this option.
  *   provider:
  *     $ref: "#/components/schemas/BaseFulfillmentProvider"
  *   shipping_option_type_id:
  *     type: string
  *     title: shipping_option_type_id
- *     description: The shipping option's shipping option type id.
+ *     description: The ID of the shipping option's type.
  *   type:
  *     $ref: "#/components/schemas/StoreShippingOption"
  *   shipping_profile_id:
  *     type: string
  *     title: shipping_profile_id
- *     description: The shipping option's shipping profile id.
+ *     description: The ID of the associated shipping profile.
  *   amount:
  *     type: number
  *     title: amount
@@ -59,13 +59,15 @@
  *   is_tax_inclusive:
  *     type: boolean
  *     title: is_tax_inclusive
- *     description: The shipping option's is tax inclusive.
+ *     description: Whether the amount includes taxes.
  *   data:
  *     type: object
- *     description: The shipping option's data.
+ *     description: The shipping option's data, useful for the provider handling fulfillment.
+ *     externalDocs:
+ *       url: https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/shipping-option#data-property
  *   metadata:
  *     type: object
- *     description: The shipping option's metadata.
+ *     description: The shipping option's metadata, can hold custom key-value pairs.
  * 
 */