chore(oas): [7/n] improve oas schemas (#9162)

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

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

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

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

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminOrderReturnResponse
  * type: object
- * description: SUMMARY
+ * description: The order return details.
  * x-schemaName: AdminOrderReturnResponse
  * required:
  *   - order

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

@@ -14,29 +14,13 @@
  *     title: id
  *     description: The payment's ID.
  *   amount:
- *     oneOf:
+ *     type: number
- *       - type: string
+ *     title: amount
- *         title: amount
+ *     description: The payment's amount.
- *         description: The payment's amount.
- *       - type: number
- *         title: amount
- *         description: The payment's amount.
- *       - type: string
- *         title: amount
- *         description: The payment's amount.
- *       - $ref: "#/components/schemas/IBigNumber"
  *   authorized_amount:
- *     oneOf:
+ *     type: number
- *       - type: string
+ *     title: authorized_amount
- *         title: authorized_amount
+ *     description: The amount authorized of the payment.
- *         description: The payment's authorized amount.
- *       - type: number
- *         title: authorized_amount
- *         description: The payment's authorized amount.
- *       - type: string
- *         title: authorized_amount
- *         description: The payment's authorized amount.
- *       - $ref: "#/components/schemas/IBigNumber"
  *   currency_code:
  *     type: string
  *     title: currency_code
@@ -44,86 +28,64 @@
  *   provider_id:
  *     type: string
  *     title: provider_id
- *     description: The payment's provider id.
+ *     description: The ID of the payment provider used to process this payment.
  *   cart_id:
  *     type: string
  *     title: cart_id
- *     description: The payment's cart id.
+ *     description: The ID of the associated cart.
  *   order_id:
  *     type: string
  *     title: order_id
- *     description: The payment's order id.
+ *     description: The ID of the associated order.
  *   order_edit_id:
  *     type: string
  *     title: order_edit_id
- *     description: The payment's order edit id.
+ *     description: The ID of the associated order edit.
  *   customer_id:
  *     type: string
  *     title: customer_id
- *     description: The payment's customer id.
+ *     description: ID of the associated customer.
  *   data:
  *     type: object
- *     description: The payment's data.
+ *     description: The payment's data, useful for processing by the payment provider.
+ *     externalDocs:
+ *       url: https://docs.medusajs.com/v2/resources/commerce-modules/payment/payment#whats-a-payment
  *   created_at:
  *     type: string
  *     format: date-time
  *     title: created_at
- *     description: The payment's created at.
+ *     description: The date the payment was created.
  *   updated_at:
  *     type: string
  *     format: date-time
  *     title: updated_at
- *     description: The payment's updated at.
+ *     description: The date the payment was updated.
  *   captured_at:
- *     oneOf:
+ *     type: string
- *       - type: string
+ *     format: date-time
- *         title: captured_at
+ *     title: captured_at
- *         description: The payment's captured at.
+ *     description: The date the payment was captured.
- *       - type: string
- *         title: captured_at
- *         description: The payment's captured at.
- *         format: date-time
  *   canceled_at:
- *     oneOf:
+ *     type: string
- *       - type: string
+ *     format: date-time
- *         title: canceled_at
+ *     title: canceled_at
- *         description: The payment's canceled at.
+ *     description: The date the payment was canceled.
- *       - type: string
- *         title: canceled_at
- *         description: The payment's canceled at.
- *         format: date-time
  *   captured_amount:
- *     oneOf:
+ *     type: number
- *       - type: string
+ *     title: captured_amount
- *         title: captured_amount
+ *     description: The captured amount of the payment.
- *         description: The payment's captured amount.
- *       - type: number
- *         title: captured_amount
- *         description: The payment's captured amount.
- *       - type: string
- *         title: captured_amount
- *         description: The payment's captured amount.
- *       - $ref: "#/components/schemas/IBigNumber"
  *   refunded_amount:
- *     oneOf:
+ *     type: number
- *       - type: string
+ *     title: captured_amount
- *         title: refunded_amount
+ *     description: The refunded amount of the payment.
- *         description: The payment's refunded amount.
- *       - type: number
- *         title: refunded_amount
- *         description: The payment's refunded amount.
- *       - type: string
- *         title: refunded_amount
- *         description: The payment's refunded amount.
- *       - $ref: "#/components/schemas/IBigNumber"
  *   captures:
  *     type: array
- *     description: The payment's captures.
+ *     description: The details of payment captures.
  *     items:
  *       $ref: "#/components/schemas/BaseCapture"
  *   refunds:
  *     type: array
- *     description: The payment's refunds.
+ *     description: The details of payment refunds.
  *     items:
  *       $ref: "#/components/schemas/BaseRefund"
  *   payment_collection:

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminPaymentCollection
  * type: object
- * description: The payment collection's payment collections.
+ * description: The payment collection's details.
  * x-schemaName: AdminPaymentCollection
  * required:
  *   - id
@@ -22,77 +22,41 @@
  *   region_id:
  *     type: string
  *     title: region_id
- *     description: The payment collection's region id.
+ *     description: The ID of the region this payment collection is associated with.
  *   amount:
- *     oneOf:
+ *     type: number
- *       - type: string
+ *     title: amount
- *         title: amount
+ *     description: The total amount to be paid.
- *         description: The payment collection's amount.
- *       - type: number
- *         title: amount
- *         description: The payment collection's amount.
- *       - type: string
- *         title: amount
- *         description: The payment collection's amount.
- *       - $ref: "#/components/schemas/IBigNumber"
  *   authorized_amount:
- *     oneOf:
+ *     type: number
- *       - type: string
+ *     title: authorized_amount
- *         title: authorized_amount
+ *     description: The total authorized amount of the collection's payments.
- *         description: The payment collection's authorized amount.
- *       - type: number
- *         title: authorized_amount
- *         description: The payment collection's authorized amount.
- *       - type: string
- *         title: authorized_amount
- *         description: The payment collection's authorized amount.
- *       - $ref: "#/components/schemas/IBigNumber"
  *   captured_amount:
- *     oneOf:
+ *     type: number
- *       - type: string
+ *     title: captured_amount
- *         title: captured_amount
+ *     description: The total captured amount of the collection's payments.
- *         description: The payment collection's captured amount.
- *       - type: number
- *         title: captured_amount
- *         description: The payment collection's captured amount.
- *       - type: string
- *         title: captured_amount
- *         description: The payment collection's captured amount.
- *       - $ref: "#/components/schemas/IBigNumber"
  *   refunded_amount:
- *     oneOf:
+ *     type: number
- *       - type: string
+ *     title: refunded_amount
- *         title: refunded_amount
+ *     description: The total refunded amount of the collection's payments.
- *         description: The payment collection's refunded amount.
- *       - type: number
- *         title: refunded_amount
- *         description: The payment collection's refunded amount.
- *       - type: string
- *         title: refunded_amount
- *         description: The payment collection's refunded amount.
- *       - $ref: "#/components/schemas/IBigNumber"
  *   completed_at:
- *     oneOf:
+ *     type: string
- *       - type: string
+ *     format: date-time
- *         title: completed_at
+ *     title: completed_at
- *         description: The payment collection's completed at.
+ *     description: The date the payment collection was completed.
- *       - type: string
- *         title: completed_at
- *         description: The payment collection's completed at.
- *         format: date-time
  *   created_at:
  *     type: string
  *     format: date-time
  *     title: created_at
- *     description: The payment collection's created at.
+ *     description: The date the payment collection was created.
  *   updated_at:
  *     type: string
  *     format: date-time
  *     title: updated_at
- *     description: The payment collection's updated at.
+ *     description: The date the payment collection was updated.
  *   metadata:
  *     type: object
- *     description: The payment collection's metadata.
+ *     description: The payment collection's metadata, can hold custom key-value pairs.
  *   status:
  *     type: string
  *     description: The payment collection's status.
@@ -104,7 +68,7 @@
  *       - partially_authorized
  *   payment_providers:
  *     type: array
- *     description: The payment collection's payment providers.
+ *     description: The payment provider used to process the collection's payments and sessions.
  *     items:
  *       $ref: "#/components/schemas/BasePaymentProvider"
  *   payment_sessions:

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

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

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

@@ -1,8 +1,20 @@
 /**
  * @schema AdminPaymentProvider
  * type: object
- * description: The payment provider's payment providers.
+ * description: The payment provider's details.
  * x-schemaName: AdminPaymentProvider
+ * required:
+ *   - is_enabled
+ *   - id
+ * properties:
+ *   id:
+ *     type: string
+ *     title: id
+ *     description: The payment provider's ID.
+ *   is_enabled:
+ *     type: boolean
+ *     title: is_enabled
+ *     description: Whether the payment provider is enabled.
  * 
 */
 

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

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

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

@@ -1,13 +1,13 @@
 /**
  * @schema AdminPostCancelClaimReqSchema
  * type: object
- * description: SUMMARY
+ * description: The details of canceling a claim.
  * x-schemaName: AdminPostCancelClaimReqSchema
  * properties:
  *   no_notification:
  *     type: boolean
  *     title: no_notification
- *     description: The claim's no notification.
+ *     description: Whether to send the customer a notification about the claim's cancelation.
  * 
 */
 

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

@@ -1,13 +1,13 @@
 /**
  * @schema AdminPostCancelExchangeReqSchema
  * type: object
- * description: SUMMARY
+ * description: The details of canceling an exchange.
  * x-schemaName: AdminPostCancelExchangeReqSchema
  * properties:
  *   no_notification:
  *     type: boolean
  *     title: no_notification
- *     description: The exchange's no notification.
+ *     description: Whether to send a notification to the customer about the exchange's cancelation.
  * 
 */
 

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

@@ -1,13 +1,13 @@
 /**
  * @schema AdminPostCancelReturnReqSchema
  * type: object
- * description: SUMMARY
+ * description: The details of canceling a return.
  * x-schemaName: AdminPostCancelReturnReqSchema
  * properties:
  *   no_notification:
  *     type: boolean
  *     title: no_notification
- *     description: The return's no notification.
+ *     description: Whether to send the customer a notification about the return's cancelation.
  * 
 */
 

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

@@ -1,15 +1,15 @@
 /**
  * @schema AdminPostClaimItemsReqSchema
  * type: object
- * description: SUMMARY
+ * description: The details of the order items to add to the claim.
  * x-schemaName: AdminPostClaimItemsReqSchema
  * properties:
  *   items:
  *     type: array
- *     description: The claim's items.
+ *     description: The item's details.
  *     items:
  *       type: object
- *       description: The item's items.
+ *       description: An item's details.
  *       required:
  *         - id
  *         - quantity
@@ -17,14 +17,14 @@
  *         id:
  *           type: string
  *           title: id
- *           description: The item's ID.
+ *           description: The ID of the order's item.
  *         quantity:
  *           type: number
  *           title: quantity
- *           description: The item's quantity.
+ *           description: The quantity of the order's item to add to the claim.
  *         reason:
  *           type: string
- *           description: The item's reason.
+ *           description: The reason the item is claimed.
  *           enum:
  *             - missing_item
  *             - wrong_item
@@ -37,7 +37,7 @@
  *         internal_note:
  *           type: string
  *           title: internal_note
- *           description: The item's internal note.
+ *           description: A note that's only viewed by admin users.
  * 
 */
 

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

@@ -1,15 +1,15 @@
 /**
  * @schema AdminPostClaimsAddItemsReqSchema
  * type: object
- * description: SUMMARY
+ * description: The details of the outbound items to add to the claim.
  * x-schemaName: AdminPostClaimsAddItemsReqSchema
  * properties:
  *   items:
  *     type: array
- *     description: The claim's items.
+ *     description: The outbound item's details.
  *     items:
  *       type: object
- *       description: The item's items.
+ *       description: An item's details.
  *       required:
  *         - variant_id
  *         - quantity
@@ -17,11 +17,11 @@
  *         variant_id:
  *           type: string
  *           title: variant_id
- *           description: The item's variant id.
+ *           description: The ID of the associated product variant.
  *         quantity:
  *           type: number
  *           title: quantity
- *           description: The item's quantity.
+ *           description: The quantity to send to the customer.
  *         unit_price:
  *           type: number
  *           title: unit_price
@@ -29,10 +29,10 @@
  *         internal_note:
  *           type: string
  *           title: internal_note
- *           description: The item's internal note.
+ *           description: A note viewed only by admin users.
  *         metadata:
  *           type: object
- *           description: The item's metadata.
+ *           description: The item's metadata, can hold custom key-value pairs.
  * 
 */
 

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

@@ -1,21 +1,21 @@
 /**
  * @schema AdminPostClaimsItemsActionReqSchema
  * type: object
- * description: SUMMARY
+ * description: The details to update in the item.
  * x-schemaName: AdminPostClaimsItemsActionReqSchema
  * properties:
  *   quantity:
  *     type: number
  *     title: quantity
- *     description: The claim's quantity.
+ *     description: The item's quantity.
  *   reason_id:
  *     type: string
  *     title: reason_id
- *     description: The claim's reason id.
+ *     description: The ID of the return reason associated with the item.
  *   internal_note:
  *     type: string
  *     title: internal_note
- *     description: The claim's internal note.
+ *     description: A note that's only viewed by admin users.
  * 
 */
 

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

@@ -1,20 +1,20 @@
 /**
  * @schema AdminPostClaimsShippingActionReqSchema
  * type: object
- * description: SUMMARY
+ * description: The details to update in the shipping method.
  * x-schemaName: AdminPostClaimsShippingActionReqSchema
  * properties:
  *   custom_amount:
  *     type: number
  *     title: custom_amount
- *     description: The claim's custom amount.
+ *     description: The shipping method's custom amount.
  *   internal_note:
  *     type: string
  *     title: internal_note
- *     description: The claim's internal note.
+ *     description: A note only viewed by admin users.
  *   metadata:
  *     type: object
- *     description: The claim's metadata.
+ *     description: The claim's metadata, can hold custom key-value pairs.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminPostClaimsShippingReqSchema
  * type: object
- * description: SUMMARY
+ * description: The details of the shipping method used to ship outbound items.
  * x-schemaName: AdminPostClaimsShippingReqSchema
  * required:
  *   - shipping_option_id
@@ -9,22 +9,22 @@
  *   shipping_option_id:
  *     type: string
  *     title: shipping_option_id
- *     description: The claim's shipping option id.
+ *     description: The ID of the associated shipping option.
  *   custom_amount:
  *     type: number
  *     title: custom_amount
- *     description: The claim's custom amount.
+ *     description: Set a custom price for the shipping method.
  *   description:
  *     type: string
  *     title: description
- *     description: The claim's description.
+ *     description: The shipping method's description.
  *   internal_note:
  *     type: string
  *     title: internal_note
- *     description: The claim's internal note.
+ *     description: A note only viewed by admin users.
  *   metadata:
  *     type: object
- *     description: The claim's metadata.
+ *     description: The claim's metadata, can hold custom key-value pairs.
  * 
 */
 

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

@@ -1,15 +1,15 @@
 /**
  * @schema AdminPostExchangesAddItemsReqSchema
  * type: object
- * description: SUMMARY
+ * description: The details of outbound items.
  * x-schemaName: AdminPostExchangesAddItemsReqSchema
  * properties:
  *   items:
  *     type: array
- *     description: The exchange's items.
+ *     description: The details of outbound items.
  *     items:
  *       type: object
- *       description: The item's items.
+ *       description: An item's details.
  *       required:
  *         - variant_id
  *         - quantity
@@ -17,7 +17,7 @@
  *         variant_id:
  *           type: string
  *           title: variant_id
- *           description: The item's variant id.
+ *           description: The ID of the associated product variant.
  *         quantity:
  *           type: number
  *           title: quantity
@@ -29,14 +29,14 @@
  *         internal_note:
  *           type: string
  *           title: internal_note
- *           description: The item's internal note.
+ *           description: A note viewed only by admin users.
  *         allow_backorder:
  *           type: boolean
  *           title: allow_backorder
- *           description: The item's allow backorder.
+ *           description: Whether the item can be added even if it's not in stock.
  *         metadata:
  *           type: object
- *           description: The item's metadata.
+ *           description: The item's metadata, can hold custom key-value pairs.
  * 
 */
 

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

@@ -1,17 +1,17 @@
 /**
  * @schema AdminPostExchangesItemsActionReqSchema
  * type: object
- * description: SUMMARY
+ * description: The details to update in an outbound item.
  * x-schemaName: AdminPostExchangesItemsActionReqSchema
  * properties:
  *   quantity:
  *     type: number
  *     title: quantity
- *     description: The exchange's quantity.
+ *     description: The item's quantity.
  *   internal_note:
  *     type: string
  *     title: internal_note
- *     description: The exchange's internal note.
+ *     description: A note only viewed by admin users.
  * 
 */
 

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

@@ -1,24 +1,24 @@
 /**
  * @schema AdminPostExchangesRequestItemsReturnActionReqSchema
  * type: object
- * description: SUMMARY
+ * description: The details to update in an inbound (returned) item.
  * x-schemaName: AdminPostExchangesRequestItemsReturnActionReqSchema
  * properties:
  *   quantity:
  *     type: number
  *     title: quantity
- *     description: The exchange's quantity.
+ *     description: The item's quantity.
  *   internal_note:
  *     type: string
  *     title: internal_note
- *     description: The exchange's internal note.
+ *     description: A note viewed only by admin users.
  *   reason_id:
  *     type: string
  *     title: reason_id
- *     description: The exchange's reason id.
+ *     description: The ID of the associated return reason.
  *   metadata:
  *     type: object
- *     description: The exchange's metadata.
+ *     description: The exchange's metadata, can hold custom key-value pairs.
  * 
 */
 

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

@@ -1,15 +1,15 @@
 /**
  * @schema AdminPostExchangesReturnRequestItemsReqSchema
  * type: object
- * description: SUMMARY
+ * description: The details of the inbound (return) items.
  * x-schemaName: AdminPostExchangesReturnRequestItemsReqSchema
  * properties:
  *   items:
  *     type: array
- *     description: The exchange's items.
+ *     description: The details of the inbound (return) items.
  *     items:
  *       type: object
- *       description: The item's items.
+ *       description: An item's details.
  *       required:
  *         - id
  *         - quantity
@@ -17,7 +17,7 @@
  *         id:
  *           type: string
  *           title: id
- *           description: The item's ID.
+ *           description: The ID of the order's item.
  *         quantity:
  *           type: number
  *           title: quantity
@@ -29,14 +29,14 @@
  *         internal_note:
  *           type: string
  *           title: internal_note
- *           description: The item's internal note.
+ *           description: A note viewed only by admin users.
  *         reason_id:
  *           type: string
  *           title: reason_id
- *           description: The item's reason id.
+ *           description: The ID of the return reason to associate with the item.
  *         metadata:
  *           type: object
- *           description: The item's metadata.
+ *           description: The item's metadata, can hold custom key-value pairs.
  * 
 */