oas: [1/n] improve oas schemas (#9039)

www/utils/generated/oas-output/operations/admin/post_admin_fulfillments_[id]_cancel.ts

@@ -36,11 +36,6 @@
  *   - api_token: []
  *   - cookie_auth: []
  *   - jwt_token: []
- * requestBody:
- *   content:
- *     application/json:
- *       schema:
- *         $ref: "#/components/schemas/AdminCancelFulfillment"
  * x-codeSamples:
  *   - lang: Shell
  *     label: cURL

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminApiKey
  * type: object
- * description: The api key's details.
+ * description: The API key's details.
  * x-schemaName: AdminApiKey
  * required:
  *   - id
@@ -26,39 +26,40 @@
  *   redacted:
  *     type: string
  *     title: redacted
- *     description: The api key's redacted.
+ *     description: The redacted form of the API key's token. This is useful when showing portion of the token.
+ *     example: sk_...123
  *   title:
  *     type: string
  *     title: title
  *     description: The api key's title.
  *   type:
  *     type: string
- *     description: The api key's type.
+ *     description: The api key's type. `secret` is used for a user's API key, whereas `publishable` is used for Publishable API keys.
  *     enum:
  *       - secret
  *       - publishable
  *   last_used_at:
  *     type: string
  *     title: last_used_at
- *     description: The api key's last used at.
+ *     description: The date and time the API key was last used.
  *     format: date-time
  *   created_by:
  *     type: string
  *     title: created_by
- *     description: The api key's created by.
+ *     description: The ID of the user that created the API key, if available.
  *   created_at:
  *     type: string
  *     format: date-time
  *     title: created_at
- *     description: The api key's created at.
+ *     description: The date and time the API key was created.
  *   revoked_by:
  *     type: string
  *     title: revoked_by
- *     description: The api key's revoked by.
+ *     description: The ID of the user that revoked the API key, if available.
  *   revoked_at:
  *     type: string
  *     title: revoked_at
- *     description: The api key's revoked at.
+ *     description: The date and time the API key was revoked. The API key is considered revoked when this property is set.
  *     format: date-time
  * 
 */

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminApiKeyResponse
  * type: object
- * description: SUMMARY
+ * description: The API key's details.
  * x-schemaName: AdminApiKeyResponse
  * required:
  *   - api_key

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

@@ -1,26 +1,26 @@
 /**
  * @schema AdminBatchProductRequest
  * type: object
- * description: SUMMARY
+ * description: The products to create, update, or delete.
  * x-schemaName: AdminBatchProductRequest
  * properties:
  *   create:
  *     type: array
- *     description: The product's create.
+ *     description: The products to create.
  *     items:
  *       $ref: "#/components/schemas/AdminCreateProduct"
  *   update:
  *     type: array
- *     description: The product's update.
+ *     description: The products to update.
  *     items:
  *       $ref: "#/components/schemas/AdminUpdateProduct"
  *   delete:
  *     type: array
- *     description: The product's delete.
+ *     description: The products to delete.
  *     items:
  *       type: string
  *       title: delete
- *       description: The delete's details.
+ *       description: A product's ID.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminBatchProductResponse
  * type: object
- * description: SUMMARY
+ * description: The details of the products created, updated, or deleted.
  * x-schemaName: AdminBatchProductResponse
  * required:
  *   - created
@@ -10,17 +10,17 @@
  * properties:
  *   created:
  *     type: array
- *     description: The product's created.
+ *     description: The created products
  *     items:
  *       $ref: "#/components/schemas/AdminProduct"
  *   updated:
  *     type: array
- *     description: The product's updated.
+ *     description: The updated products.
  *     items:
  *       $ref: "#/components/schemas/AdminProduct"
  *   deleted:
  *     type: object
- *     description: SUMMARY
+ *     description: The deleted products' details.
  *     required:
  *       - ids
  *       - object
@@ -28,19 +28,20 @@
  *     properties:
  *       ids:
  *         type: array
- *         description: The deleted's ids.
+ *         description: The IDs of deleted products.
  *         items:
  *           type: string
  *           title: ids
- *           description: The id's ids.
+ *           description: The ID of a deleted product.
  *       object:
  *         type: string
  *         title: object
- *         description: SUMMARY
+ *         description: The name of the deleted objects.
+ *         default: product
  *       deleted:
  *         type: boolean
  *         title: deleted
- *         description: SUMMARY
+ *         description: Whether the products were deleted.
  * 
 */
 

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

@@ -1,26 +1,26 @@
 /**
  * @schema AdminBatchProductVariantRequest
  * type: object
- * description: SUMMARY
+ * description: The product variants to create, update, or delete.
  * x-schemaName: AdminBatchProductVariantRequest
  * properties:
  *   create:
  *     type: array
- *     description: The product's create.
+ *     description: The product variants to create.
  *     items:
  *       $ref: "#/components/schemas/AdminCreateProductVariant"
  *   update:
  *     type: array
- *     description: The product's update.
+ *     description: The product variants to update.
  *     items:
  *       $ref: "#/components/schemas/AdminUpdateProductVariant"
  *   delete:
  *     type: array
- *     description: The product's delete.
+ *     description: The product variants to delete.
  *     items:
  *       type: string
  *       title: delete
- *       description: The delete's details.
+ *       description: A product variant's ID.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminBatchProductVariantResponse
  * type: object
- * description: SUMMARY
+ * description: The details of the product variants created, updated, or deleted.
  * x-schemaName: AdminBatchProductVariantResponse
  * required:
  *   - created
@@ -10,17 +10,17 @@
  * properties:
  *   created:
  *     type: array
- *     description: The product's created.
+ *     description: The created product variants.
  *     items:
  *       $ref: "#/components/schemas/AdminProductVariant"
  *   updated:
  *     type: array
- *     description: The product's updated.
+ *     description: The updated product variants.
  *     items:
  *       $ref: "#/components/schemas/AdminProductVariant"
  *   deleted:
  *     type: object
- *     description: SUMMARY
+ *     description: The details of the deleted product variants.
  *     required:
  *       - ids
  *       - object
@@ -28,19 +28,20 @@
  *     properties:
  *       ids:
  *         type: array
- *         description: The deleted's ids.
+ *         description: The IDs of the deleted product variants.
  *         items:
  *           type: string
  *           title: ids
- *           description: The id's ids.
+ *           description: The ID of a deleted variant.
  *       object:
  *         type: string
  *         title: object
- *         description: SUMMARY
+ *         description: The name of the deleted objects.
+ *         default: variant
  *       deleted:
  *         type: boolean
  *         title: deleted
- *         description: SUMMARY
+ *         description: Whether the product variants were deleted.
  * 
 */
 

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

@@ -32,15 +32,15 @@
  *   campaign_identifier:
  *     type: string
  *     title: campaign_identifier
- *     description: The campaign's campaign identifier.
+ *     description: The campaign's identifier.
  *   starts_at:
  *     type: string
  *     title: starts_at
- *     description: The campaign's starts at.
+ *     description: The date and time that the campaign starts.
  *   ends_at:
  *     type: string
  *     title: ends_at
- *     description: The campaign's ends at.
+ *     description: The date and time that the campaign ends.
  *   budget:
  *     type: object
  *     description: The campaign's budget.
@@ -57,7 +57,9 @@
  *         description: The budget's ID.
  *       type:
  *         type: string
- *         description: The budget's type.
+ *         description: >
+ *           The budget's type. `spend` means the limit is set on the total amount discounted by the campaign's promotions; `usage` means the limit is set on the total
+ *           number of times the campaign's promotions can be used.
  *         enum:
  *           - spend
  *           - usage
@@ -72,7 +74,9 @@
  *       used:
  *         type: number
  *         title: used
- *         description: The budget's used.
+ *         description: >
+ *           How much of the budget has been used. If the limit is `spend`, this property holds the total amount discounted so far. If the limit is `usage`, it holds
+ *           the number of times the campaign's promotions have been used so far.
  * 
 */
 

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

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

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

@@ -1,8 +0,0 @@
-/**
- * @schema AdminCancelFulfillment
- * type: object
- * description: SUMMARY
- * x-schemaName: AdminCancelFulfillment
- * 
-*/
-

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

@@ -43,62 +43,63 @@
  *   - original_shipping_subtotal
  *   - original_shipping_tax_total
  * properties:
+ *   id:
+ *     type: string
+ *     title: id
+ *     description: The claim's ID.
  *   order_id:
  *     type: string
  *     title: order_id
- *     description: The claim's order id.
+ *     description: The ID of the order associated with the claim.
  *   claim_items:
  *     type: array
- *     description: The claim's claim items.
+ *     description: The order items targetted by the claim.
  *     items:
  *       $ref: "#/components/schemas/BaseClaimItem"
  *   additional_items:
  *     type: array
- *     description: The claim's additional items.
+ *     description: The outbound or new items of the claim.
- *     items: {}
+ *     items:
+ *       $ref: "#/components/schemas/BaseClaimItem"
  *   return:
  *     $ref: "#/components/schemas/Return"
  *   return_id:
  *     type: string
  *     title: return_id
- *     description: The claim's return id.
+ *     description: The ID of the associated return.
  *   no_notification:
  *     type: boolean
  *     title: no_notification
- *     description: The claim's no notification.
+ *     description: Whether the customer should be notified about changes in the claim.
  *   refund_amount:
  *     type: number
  *     title: refund_amount
- *     description: The claim's refund amount.
+ *     description: The amount to be refunded.
  *   currency_code:
  *     type: string
  *     title: currency_code
  *     description: The claim's currency code.
- *   id:
- *     type: string
- *     title: id
- *     description: The claim's ID.
  *   region_id:
  *     type: string
  *     title: region_id
- *     description: The claim's region id.
+ *     description: The ID of the region associated with the claim.
  *   customer_id:
  *     type: string
  *     title: customer_id
- *     description: The claim's customer id.
+ *     description: The ID of the customer associated with the claim's order.
  *   sales_channel_id:
  *     type: string
  *     title: sales_channel_id
- *     description: The claim's sales channel id.
+ *     description: The ID of the sales channel the claim's order is created in.
  *   email:
  *     type: string
  *     title: email
- *     description: The claim's email.
+ *     description: The email associated with the claim's order.
  *     format: email
  *   display_id:
  *     type: number
  *     title: display_id
- *     description: The claim's display id.
+ *     description: The claim's display ID.
  *   shipping_address:
  *     $ref: "#/components/schemas/BaseOrderAddress"
  *   billing_address:
@@ -147,63 +148,66 @@
  *   transactions:
  *     type: array
  *     description: The claim's transactions.
+ *     externalDocs:
+ *       url: https://docs.medusajs.com/v2/resources/commerce-modules/order/transactions
+ *       description: Learn more about transactions of orders and associated models.
  *     items:
  *       $ref: "#/components/schemas/BaseOrderTransaction"
  *   summary:
  *     $ref: "#/components/schemas/BaseOrderSummary"
  *   metadata:
  *     type: object
- *     description: The claim's metadata.
+ *     description: The claim's metadata, used to store custom key-value pairs.
  *   created_at:
  *     type: string
  *     format: date-time
  *     title: created_at
- *     description: The claim's created at.
+ *     description: The claim's creation date.
  *   updated_at:
  *     type: string
  *     format: date-time
  *     title: updated_at
- *     description: The claim's updated at.
+ *     description: The claim's update date.
  *   original_item_total:
  *     type: number
  *     title: original_item_total
- *     description: The claim's original item total.
+ *     description: The total of the original items in the associated order.
  *   original_item_subtotal:
  *     type: number
  *     title: original_item_subtotal
- *     description: The claim's original item subtotal.
+ *     description: The subtotal of the original items in the associated order.
  *   original_item_tax_total:
  *     type: number
  *     title: original_item_tax_total
- *     description: The claim's original item tax total.
+ *     description: The tax total of the original items in the associated order.
  *   item_total:
  *     type: number
  *     title: item_total
- *     description: The claim's item total.
+ *     description: The total of the claim's items.
  *   item_subtotal:
  *     type: number
  *     title: item_subtotal
- *     description: The claim's item subtotal.
+ *     description: The subtotal of the claim's items.
  *   item_tax_total:
  *     type: number
  *     title: item_tax_total
- *     description: The claim's item tax total.
+ *     description: The tax total of the claim's items.
  *   original_total:
  *     type: number
  *     title: original_total
- *     description: The claim's original total.
+ *     description: The associated order's original total.
  *   original_subtotal:
  *     type: number
  *     title: original_subtotal
- *     description: The claim's original subtotal.
+ *     description: The associated order's original subtotal.
  *   original_tax_total:
  *     type: number
  *     title: original_tax_total
- *     description: The claim's original tax total.
+ *     description: The associated order's original tax total.
  *   total:
  *     type: number
  *     title: total
- *     description: The claim's total.
+ *     description: The associated order's total.
  *   subtotal:
  *     type: number
  *     title: subtotal
@@ -243,15 +247,15 @@
  *   original_shipping_total:
  *     type: number
  *     title: original_shipping_total
- *     description: The claim's original shipping total.
+ *     description: The associated order's original shipping total.
  *   original_shipping_subtotal:
  *     type: number
  *     title: original_shipping_subtotal
- *     description: The claim's original shipping subtotal.
+ *     description: The associated order's original shipping subtotal.
  *   original_shipping_tax_total:
  *     type: number
  *     title: original_shipping_tax_total
- *     description: The claim's original shipping tax total.
+ *     description: The associated order's original shipping tax total.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminClaimDeleteResponse
  * type: object
- * description: SUMMARY
+ * description: The details of the deleted claim.
  * x-schemaName: AdminClaimDeleteResponse
  * required:
  *   - id
@@ -20,7 +20,7 @@
  *   deleted:
  *     type: boolean
  *     title: deleted
- *     description: Whether the Claim was deleted.
+ *     description: Whether the claim was deleted.
  * 
 */
 

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

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

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminClaimOrderResponse
  * type: object
- * description: SUMMARY
+ * description: The created claim's details.
  * x-schemaName: AdminClaimOrderResponse
  * required:
  *   - order

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminClaimPreviewResponse
  * type: object
- * description: SUMMARY
+ * description: The details of the claim, as well as a preview of the order when the claim is applied.
  * x-schemaName: AdminClaimPreviewResponse
  * required:
  *   - order_preview

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminClaimRequestResponse
  * type: object
- * description: SUMMARY
+ * description: The details of the claim, its return, and a preview of the order when the claim is applied.
  * x-schemaName: AdminClaimRequestResponse
  * required:
  *   - return

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

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

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminClaimReturnPreviewResponse
  * type: object
- * description: SUMMARY
+ * description: The details of the claim's return, with a preview of the order when the claim's return is applied.
  * x-schemaName: AdminClaimReturnPreviewResponse
  * required:
  *   - order_preview

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminCollection
  * type: object
- * description: The parent's collection.
+ * description: The product collection's details.
  * x-schemaName: AdminCollection
  * required:
  *   - id
@@ -28,17 +28,17 @@
  *     type: string
  *     format: date-time
  *     title: created_at
- *     description: The collection's created at.
+ *     description: The collection's creation date.
  *   updated_at:
  *     type: string
  *     format: date-time
  *     title: updated_at
- *     description: The collection's updated at.
+ *     description: The collection's update date.
  *   deleted_at:
  *     type: string
  *     format: date-time
  *     title: deleted_at
- *     description: The collection's deleted at.
+ *     description: The collection's deletion date.
  *   products:
  *     type: array
  *     description: The collection's products.
@@ -46,7 +46,7 @@
  *       $ref: "#/components/schemas/AdminProduct"
  *   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/AdminCollectionDeleteResponse.ts

@@ -1,7 +1,7 @@
 /**
  * @schema AdminCollectionDeleteResponse
  * type: object
- * description: SUMMARY
+ * description: The details of the deleted collection.
  * x-schemaName: AdminCollectionDeleteResponse
  * required:
  *   - id
@@ -20,7 +20,7 @@
  *   deleted:
  *     type: boolean
  *     title: deleted
- *     description: Whether the Collection was deleted.
+ *     description: Whether the collection was deleted.
  * 
 */
 

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

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