oas: [2/n] improve schema oas (#9040)

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

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

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminCreateApiKey
  * type: object
- * description: SUMMARY
+ * description: The API key's details.
  * x-schemaName: AdminCreateApiKey
  * required:
  *   - title
@@ -10,10 +10,10 @@
  *   title:
  *     type: string
  *     title: title
- *     description: The api key's title.
+ *     description: The API key's title.
  *   type:
  *     type: string
- *     description: The api key's type.
+ *     description: The API key's type. Use `secret` for a user's API key; Use `publishable` for Publishable API keys.
  *     enum:
  *       - publishable
  *       - secret

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminCreateApplicationMethod
  * type: object
- * description: The promotion's application method.
+ * description: The application method's details.
  * x-schemaName: AdminCreateApplicationMethod
  * required:
  *   - value
@@ -15,31 +15,31 @@
  *   value:
  *     type: number
  *     title: value
- *     description: The application method's value.
+ *     description: The discounted amount applied by the associated promotion based on the `type`.
  *   currency_code:
  *     type: string
  *     title: currency_code
  *     description: The application method's currency code.
  *   max_quantity:
  *     type: number
  *     title: max_quantity
- *     description: The application method's max quantity.
+ *     description: The max quantity allowed in the cart for the associated promotion to be applied.
  *   type:
  *     type: string
- *     description: The application method's type.
+ *     description: The type of the application method indicating how the associated promotion is applied.
  *     enum:
  *       - fixed
  *       - percentage
  *   target_type:
  *     type: string
- *     description: The application method's target type.
+ *     description: The target type of the application method indicating whether the associated promotion is applied to the cart's items, shipping methods, or the whole order.
  *     enum:
  *       - items
  *       - shipping_methods
  *       - order
  *   allocation:
  *     type: string
- *     description: The application method's allocation.
+ *     description: The allocation value that indicates whether the associated promotion is applied on each item in a cart or split between the items in the cart.
  *     enum:
  *       - each
  *       - across
@@ -56,11 +56,11 @@
  *   apply_to_quantity:
  *     type: number
  *     title: apply_to_quantity
- *     description: The application method's apply to quantity.
+ *     description: The quantity that results from matching the `buyget` promotion's condition. For example, if the promotion is a "Buy 2 shirts get 1 free", the value f this attribute is `1`.
  *   buy_rules_min_quantity:
  *     type: number
  *     title: buy_rules_min_quantity
- *     description: The application method's buy rules min quantity.
+ *     description: The minimum quantity required for a `buyget` promotion to be applied. For example, if the promotion is a "Buy 2 shirts get 1 free", the value of this attribute is `2`.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminCreateCollection
  * type: object
- * description: SUMMARY
+ * description: the product collection's details.
  * x-schemaName: AdminCreateCollection
  * required:
  *   - title
@@ -16,7 +16,7 @@
  *     description: The collection's handle.
  *   metadata:
  *     type: object
- *     description: The collection's metadata.
+ *     description: The collection's metadata, used to store custom key-value pairs.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminCreateCustomerGroup
  * type: object
- * description: SUMMARY
+ * description: The customer group's details.
  * x-schemaName: AdminCreateCustomerGroup
  * required:
  *   - name
@@ -12,7 +12,7 @@
  *     description: The customer group's name.
  *   metadata:
  *     type: object
- *     description: The customer group's metadata.
+ *     description: The customer group's metadata, used to store custom key-value pairs.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminCreateFulfillment
  * type: object
- * description: SUMMARY
+ * description: The filfillment's details.
  * x-schemaName: AdminCreateFulfillment
  * required:
  *   - location_id
@@ -17,39 +17,39 @@
  *   location_id:
  *     type: string
  *     title: location_id
- *     description: The fulfillment's location id.
+ *     description: The ID of the location the items are fulfilled from.
  *   provider_id:
  *     type: string
  *     title: provider_id
- *     description: The fulfillment's provider id.
+ *     description: The ID of the provider handling this fulfillment.
  *   delivery_address:
  *     type: object
- *     description: The fulfillment's delivery address.
+ *     description: The address to deliver the items to.
  *     properties:
  *       first_name:
  *         type: string
  *         title: first_name
- *         description: The delivery address's first name.
+ *         description: The customer's first name.
  *       last_name:
  *         type: string
  *         title: last_name
- *         description: The delivery address's last name.
+ *         description: The customer's last name.
  *       phone:
  *         type: string
  *         title: phone
- *         description: The delivery address's phone.
+ *         description: The customer's phone.
  *       company:
  *         type: string
  *         title: company
  *         description: The delivery address's company.
  *       address_1:
  *         type: string
  *         title: address_1
- *         description: The delivery address's address 1.
+ *         description: The delivery address's first line.
  *       address_2:
  *         type: string
  *         title: address_2
- *         description: The delivery address's address 2.
+ *         description: The delivery address's second line.
  *       city:
  *         type: string
  *         title: city
@@ -68,13 +68,13 @@
  *         description: The delivery address's postal code.
  *       metadata:
  *         type: object
- *         description: The delivery address's metadata.
+ *         description: The delivery address's metadata, used to store custom key-value pairs.
  *   items:
  *     type: array
- *     description: The fulfillment's items.
+ *     description: The items to fulfill.
  *     items:
  *       type: object
- *       description: The item's items.
+ *       description: An item to fulfill.
  *       required:
  *         - title
  *         - sku
@@ -88,29 +88,29 @@
  *         sku:
  *           type: string
  *           title: sku
- *           description: The item's sku.
+ *           description: The item's SKU.
  *         quantity:
  *           type: number
  *           title: quantity
- *           description: The item's quantity.
+ *           description: The quantity to fulfill of the item.
  *         barcode:
  *           type: string
  *           title: barcode
  *           description: The item's barcode.
  *         line_item_id:
  *           type: string
  *           title: line_item_id
- *           description: The item's line item id.
+ *           description: The ID of the associated line item.
  *         inventory_item_id:
  *           type: string
  *           title: inventory_item_id
- *           description: The item's inventory item id.
+ *           description: The ID of the inventory item associated with the underlying variant.
  *   labels:
  *     type: array
- *     description: The fulfillment's labels.
+ *     description: The labels for the fulfillment's shipments.
  *     items:
  *       type: object
- *       description: The label's labels.
+ *       description: A shipment's label.
  *       required:
  *         - tracking_number
  *         - tracking_url
@@ -123,48 +123,48 @@
  *         tracking_url:
  *           type: string
  *           title: tracking_url
- *           description: The label's tracking url.
+ *           description: The label's tracking URL.
  *         label_url:
  *           type: string
  *           title: label_url
- *           description: The label's label url.
- *   order:
- *     type: object
- *     description: The fulfillment's order.
+ *           description: The label's URL.
  *   order_id:
  *     type: string
  *     title: order_id
- *     description: The fulfillment's order id.
+ *     description: The ID of the order this fulfillment is created for.
  *   shipping_option_id:
  *     type: string
  *     title: shipping_option_id
- *     description: The fulfillment's shipping option id.
+ *     description: The ID of the shipping option used in the order.
  *   data:
  *     type: object
- *     description: The fulfillment's data.
+ *     description: Any data useful for the fulfillment provider to handle the fulfillment.
+ *     externalDocs:
+ *       url: https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/shipping-option#data-property
+ *       description: Learn more about the data property.
  *   packed_at:
  *     type: string
  *     title: packed_at
- *     description: The fulfillment's packed at.
+ *     description: The date and time the fulfillment was packed.
  *     format: date-time
  *   shipped_at:
  *     type: string
  *     title: shipped_at
- *     description: The fulfillment's shipped at.
+ *     description: The date and time the fulfillment was shipped.
  *     format: date-time
  *   delivered_at:
  *     type: string
  *     title: delivered_at
- *     description: The fulfillment's delivered at.
+ *     description: The date and time the fulfillment was delivered.
  *     format: date-time
  *   canceled_at:
  *     type: string
  *     title: canceled_at
- *     description: The fulfillment's canceled at.
+ *     description: The date and time the fulfillment was canceled.
  *     format: date-time
  *   metadata:
  *     type: object
- *     description: The fulfillment's metadata.
+ *     description: The fulfillment's metadata, used to store custom key-value pairs.
  * 
 */
 

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

@@ -1,17 +1,17 @@
 /**
  * @schema AdminCreateInventoryItem
  * type: object
- * description: SUMMARY
+ * description: The inventory item's details.
  * x-schemaName: AdminCreateInventoryItem
  * properties:
  *   sku:
  *     type: string
  *     title: sku
- *     description: The inventory item's sku.
+ *     description: The inventory item's SKU.
  *   hs_code:
  *     type: string
  *     title: hs_code
- *     description: The inventory item's hs code.
+ *     description: The inventory item's HS code.
  *   weight:
  *     type: number
  *     title: weight
@@ -47,18 +47,18 @@
  *   description:
  *     type: string
  *     title: description
- *     description: The inventory item's description.
+ *     description: The description of the variant associated with the inventory item.
  *   requires_shipping:
  *     type: boolean
  *     title: requires_shipping
- *     description: The inventory item's requires shipping.
+ *     description: Whether the item requires shipping.
  *   thumbnail:
  *     type: string
  *     title: thumbnail
  *     description: The inventory item's thumbnail.
  *   metadata:
  *     type: object
- *     description: The inventory item's metadata.
+ *     description: The inventory item's metadata, used to store custom key-value pairs.
  * 
 */