oas: [3/n] improve oas schemas (#9042)

Improve oas schemas [3/n]

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminCreateSalesChannel
  * type: object
- * description: SUMMARY
+ * description: The sales channel's details.
  * x-schemaName: AdminCreateSalesChannel
  * required:
  *   - name
@@ -17,10 +17,10 @@
  *   is_disabled:
  *     type: boolean
  *     title: is_disabled
- *     description: The sales channel's is disabled.
+ *     description: Whether the sales channel is disabled.
  *   metadata:
  *     type: object
- *     description: The sales channel's metadata.
+ *     description: The sales channel's metadata, used to store custom key-value pairs.
  * 
 */
 

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

@@ -1,17 +1,17 @@
 /**
  * @schema AdminCreateShipment
  * type: object
- * description: SUMMARY
+ * description: The shipment's details.
  * x-schemaName: AdminCreateShipment
  * required:
  *   - labels
  * properties:
  *   labels:
  *     type: array
- *     description: The fulfillment's labels.
+ *     description: The shipment's labels.
  *     items:
  *       type: object
- *       description: The label's labels.
+ *       description: A shipment label's details.
  *       required:
  *         - tracking_number
  *         - tracking_url
@@ -24,11 +24,11 @@
  *         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.
+ *           description: The label's URL.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminCreateShippingOption
  * type: object
- * description: SUMMARY
+ * description: The shipping option's details.
  * x-schemaName: AdminCreateShippingOption
  * required:
  *   - name
@@ -19,33 +19,38 @@
  *   service_zone_id:
  *     type: string
  *     title: service_zone_id
- *     description: The shipping option's service zone id.
+ *     description: The ID of the service zone this shipping option belongs to.
  *   shipping_profile_id:
  *     type: string
  *     title: shipping_profile_id
- *     description: The shipping option's shipping profile id.
+ *     description: The ID of the shipping profile this shipping option belongs to.
  *   data:
  *     type: object
- *     description: The shipping option's data.
+ *     description: Any data necessary for fulfillment providers to handle shipping methods and fulfillments of this shipping option.
+ *     externalDocs:
+ *       url: https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/shipping-option#data-property
+ *       description: Learn more about the data property.
  *   price_type:
  *     type: string
- *     description: The shipping option's price type.
+ *     description: >
+ *       The shipping option price's type. If `flat`, it means the option has a fixed price set in the `prices` property.
+ *       `calculated` means that the shipping option's price is calculated during checkout.
  *     enum:
  *       - flat
  *       - calculated
  *   provider_id:
  *     type: string
  *     title: provider_id
- *     description: The shipping option's provider id.
+ *     description: The ID of the fulfillment provider used to handle this shipping option and its associated methods and fulfillments.
  *   type:
  *     $ref: "#/components/schemas/AdminCreateShippingOption"
  *   prices:
  *     type: array
- *     description: The shipping option's prices.
+ *     description: The shipping option's prices. If `price_type` is `calculated`, pass an empty array for this property.
  *     items:
  *       oneOf:
  *         - type: object
- *           description: The price's prices.
+ *           description: The price for a currency code.
  *           x-schemaName: AdminCreateShippingOptionPriceWithCurrency
  *           required:
  *             - currency_code
@@ -60,7 +65,7 @@
  *               title: amount
  *               description: The price's amount.
  *         - type: object
- *           description: The price's prices.
+ *           description: The price in a region.
  *           x-schemaName: AdminCreateShippingOptionPriceWithRegion
  *           required:
  *             - region_id
@@ -69,7 +74,7 @@
  *             region_id:
  *               type: string
  *               title: region_id
- *               description: The price's region id.
+ *               description: The ID of the region this price is used in.
  *             amount:
  *               type: number
  *               title: amount

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminCreateShippingOptionRule
  * type: object
- * description: The rule's rules.
+ * description: The details of the shipping option rule.
  * x-schemaName: AdminCreateShippingOptionRule
  * required:
  *   - operator
@@ -10,7 +10,7 @@
  * properties:
  *   operator:
  *     type: string
- *     description: The rule's operator.
+ *     description: The operator used to check whether a rule applies.
  *     enum:
  *       - gt
  *       - lt
@@ -23,18 +23,21 @@
  *   attribute:
  *     type: string
  *     title: attribute
- *     description: The rule's attribute.
+ *     description: The name of a property or table that the rule applies to.
+ *     example: customer_group
  *   value:
  *     oneOf:
  *       - type: string
  *         title: value
- *         description: The rule's value.
+ *         description: A value of the attribute that enables this rule.
+ *         example: cusgroup_123
  *       - type: array
- *         description: The rule's value.
+ *         description: Values of the attribute that enable this rule.
  *         items:
  *           type: string
  *           title: value
- *           description: The value's details.
+ *           description: A value of the attribute that enables this rule.
+ *           example: cusgroup_123
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminCreateShippingProfile
  * type: object
- * description: SUMMARY
+ * description: The shipping profile's details.
  * x-schemaName: AdminCreateShippingProfile
  * required:
  *   - name
@@ -17,7 +17,7 @@
  *     description: The shipping profile's type.
  *   metadata:
  *     type: object
- *     description: The shipping profile's metadata.
+ *     description: The shipping profile's metadata, used to store custom key-value pairs.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminCreateStockLocation
  * type: object
- * description: SUMMARY
+ * description: The stock location's details.
  * x-schemaName: AdminCreateStockLocation
  * required:
  *   - name
@@ -13,12 +13,12 @@
  *   address_id:
  *     type: string
  *     title: address_id
- *     description: The stock location's address id.
+ *     description: The ID of the stock location's address.
  *   address:
  *     $ref: "#/components/schemas/AdminUpsertStockLocationAddress"
  *   metadata:
  *     type: object
- *     description: The stock location's metadata.
+ *     description: The stock location's metadata, used to store custom key-value pairs.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminCreateTaxRate
  * type: object
- * description: SUMMARY
+ * description: The tax rate's details.
  * x-schemaName: AdminCreateTaxRate
  * required:
  *   - name
@@ -11,18 +11,20 @@
  *     type: string
  *     title: name
  *     description: The tax rate's name.
+ *     example: VAT
  *   tax_region_id:
  *     type: string
  *     title: tax_region_id
- *     description: The tax rate's tax region id.
+ *     description: The ID of the tax region this rate belongs to.
  *   rate:
  *     type: number
  *     title: rate
- *     description: The tax rate's rate.
+ *     description: The rate to charge.
+ *     example: 10
  *   code:
  *     type: string
  *     title: code
- *     description: The tax rate's code.
+ *     description: The code the tax rate is identified by.
  *   rules:
  *     type: array
  *     description: The tax rate's rules.
@@ -31,14 +33,16 @@
  *   is_default:
  *     type: boolean
  *     title: is_default
- *     description: The tax rate's is default.
+ *     description: Whether the tax rate is the default in its tax region.
  *   is_combinable:
  *     type: boolean
  *     title: is_combinable
- *     description: The tax rate's is combinable.
+ *     description: Whether the tax rate should be combined with parent rates.
+ *     externalDocs:
+ *       url: https://docs.medusajs.com/v2/resources/commerce-modules/tax/tax-rates-and-rules#combinable-tax-rates
  *   metadata:
  *     type: object
- *     description: The tax rate's metadata.
+ *     description: The tax rate's metadata, used to store custom key-value pairs.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminCreateTaxRateRule
  * type: object
- * description: SUMMARY
+ * description: The tax rate rule's details.
  * x-schemaName: AdminCreateTaxRateRule
  * required:
  *   - reference
@@ -10,11 +10,13 @@
  *   reference:
  *     type: string
  *     title: reference
- *     description: The tax rate's reference.
+ *     description: The name of a table in the database that this rule points to.
+ *     example: product_type
  *   reference_id:
  *     type: string
  *     title: reference_id
- *     description: The tax rate's reference id.
+ *     description: The ID of a record in the table specified in reference.
+ *     example: ptype_123
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminCreateTaxRegion
  * type: object
- * description: SUMMARY
+ * description: The tax region's details.
  * x-schemaName: AdminCreateTaxRegion
  * required:
  *   - country_code
@@ -10,6 +10,7 @@
  *     type: string
  *     title: country_code
  *     description: The tax region's country code.
+ *     example: us
  *   province_code:
  *     type: string
  *     title: province_code
@@ -17,7 +18,7 @@
  *   parent_id:
  *     type: string
  *     title: parent_id
- *     description: The tax region's parent id.
+ *     description: The ID of the parent tax region.
  *   default_tax_rate:
  *     type: object
  *     description: The tax region's default tax rate.
@@ -27,25 +28,28 @@
  *       rate:
  *         type: number
  *         title: rate
- *         description: The default tax rate's rate.
+ *         description: The rate to charge.
+ *         example: 10
  *       code:
  *         type: string
  *         title: code
- *         description: The default tax rate's code.
+ *         description: The code the tax rate is identified by
  *       name:
  *         type: string
  *         title: name
  *         description: The default tax rate's name.
+ *         example: VAT
  *       is_combinable:
  *         type: boolean
- *         title: is_combinable
+ *         description: Whether the tax rate should be combined with parent rates.
- *         description: The default tax rate's is combinable.
+ *         externalDocs:
+ *           url: https://docs.medusajs.com/v2/resources/commerce-modules/tax/tax-rates-and-rules#combinable-tax-rates
  *       metadata:
  *         type: object
- *         description: The default tax rate's metadata.
+ *         description: The default tax rate's metadata, used to store custom key-value pairs.
  *   metadata:
  *     type: object
- *     description: The tax region's metadata.
+ *     description: The tax region's metadata, used to store custom key-value pairs.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminCreateVariantInventoryItem
  * type: object
- * description: SUMMARY
+ * description: The details of the variant-inventory item association.
  * x-schemaName: AdminCreateVariantInventoryItem
  * required:
  *   - required_quantity
@@ -10,11 +10,11 @@
  *   required_quantity:
  *     type: number
  *     title: required_quantity
- *     description: The product's required quantity.
+ *     description: The quantity of the variant in the inventory item.
  *   inventory_item_id:
  *     type: string
  *     title: inventory_item_id
- *     description: The product's inventory item id.
+ *     description: The inventory item's ID.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminCreateWorkflowsAsyncResponse
  * type: object
- * description: SUMMARY
+ * description: The details of changing a workflow execution's step status.
  * x-schemaName: AdminCreateWorkflowsAsyncResponse
  * required:
  *   - transaction_id
@@ -10,16 +10,18 @@
  *   transaction_id:
  *     type: string
  *     title: transaction_id
- *     description: The workflows execution's transaction id.
+ *     description: The workflows execution's transaction ID.
  *   step_id:
  *     type: string
  *     title: step_id
- *     description: The workflows execution's step id.
+ *     description: The ID of the step whose status was changed.
- *   response: {}
+ *   response:
- *   compensate_input: {}
+ *     description: Sets the step's response. It accepts any type.
+ *   compensate_input:
+ *     description: Sets the compensation function's input. It accepts any response.
  *   action:
  *     type: string
- *     description: The workflows execution's action.
+ *     description: Whether to invoke or compensate the step.
  *     enum:
  *       - invoke
  *       - compensate

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

@@ -1,14 +1,15 @@
 /**
  * @schema AdminCreateWorkflowsRun
  * type: object
- * description: SUMMARY
+ * description: The details of the workflow to execute.
  * x-schemaName: AdminCreateWorkflowsRun
  * properties:
- *   input: {}
+ *   input:
+ *     description: The input to pass to the workflow. Can be of any type.
  *   transaction_id:
  *     type: string
  *     title: transaction_id
- *     description: The workflows execution's transaction id.
+ *     description: The ID of the workflow execution's transaction.
  * 
 */
 

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

@@ -1,8 +1,62 @@
 /**
  * @schema AdminCurrency
  * type: object
- * description: The supported currency's currency.
+ * description: The currency's currencies.
  * x-schemaName: AdminCurrency
+ * required:
+ *   - code
+ *   - symbol
+ *   - symbol_native
+ *   - name
+ *   - decimal_digits
+ *   - rounding
+ *   - raw_rounding
+ *   - created_at
+ *   - updated_at
+ *   - deleted_at
+ * properties:
+ *   code:
+ *     type: string
+ *     title: code
+ *     description: The currency's code.
+ *     example: usd
+ *   symbol:
+ *     type: string
+ *     title: symbol
+ *     description: The currency's symbol.
+ *     example: $
+ *   symbol_native:
+ *     type: string
+ *     title: symbol_native
+ *     description: The currency's native symbol, if different than the symbol.
+ *     example: $
+ *   name:
+ *     type: string
+ *     title: name
+ *     description: The currency's name.
+ *   decimal_digits:
+ *     type: number
+ *     title: decimal_digits
+ *     description: The number of digits after the decimal for prices in this currency.
+ *   rounding:
+ *     type: number
+ *     title: rounding
+ *     description: The rounding percision applied on prices in this currency.
+ *   created_at:
+ *     type: string
+ *     format: date-time
+ *     title: created_at
+ *     description: The currency's creation date.
+ *   updated_at:
+ *     type: string
+ *     format: date-time
+ *     title: updated_at
+ *     description: The currency's update date.
+ *   deleted_at:
+ *     type: string
+ *     format: date-time
+ *     title: deleted_at
+ *     description: The currency's deletion date.
  * 
 */
 

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

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

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

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

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminCustomer
  * type: object
- * description: The order's customer.
+ * description: The customer's details.
  * x-schemaName: AdminCustomer
  * required:
  *   - has_account
@@ -14,19 +14,19 @@
  *   - last_name
  *   - addresses
  * properties:
+ *   id:
+ *     type: string
+ *     title: id
+ *     description: The customer's ID.
  *   has_account:
  *     type: boolean
  *     title: has_account
- *     description: The customer's has account.
+ *     description: Whether the customer is registered.
  *   groups:
  *     type: array
  *     description: The customer's groups.
  *     items:
  *       $ref: "#/components/schemas/AdminCustomerGroup"
- *   id:
- *     type: string
- *     title: id
- *     description: The customer's ID.
  *   email:
  *     type: string
  *     title: email
@@ -35,11 +35,11 @@
  *   default_billing_address_id:
  *     type: string
  *     title: default_billing_address_id
- *     description: The customer's default billing address id.
+ *     description: The ID of the address used as the default billing address.
  *   default_shipping_address_id:
  *     type: string
  *     title: default_shipping_address_id
- *     description: The customer's default shipping address id.
+ *     description: The ID of the address used as the default shipping address.
  *   company_name:
  *     type: string
  *     title: company_name
@@ -63,26 +63,26 @@
  *     description: The customer's phone.
  *   metadata:
  *     type: object
- *     description: The customer's metadata.
+ *     description: The customer's metadata, used to store custom key-value pairs.
  *   created_by:
  *     type: string
  *     title: created_by
- *     description: The customer's created by.
+ *     description: The ID of the user that created this customer, if available.
- *   deleted_at:
- *     type: string
- *     format: date-time
- *     title: deleted_at
- *     description: The customer's deleted at.
  *   created_at:
  *     type: string
  *     format: date-time
  *     title: created_at
- *     description: The customer's created at.
+ *     description: The customer's creation date.
  *   updated_at:
  *     type: string
  *     format: date-time
  *     title: updated_at
- *     description: The customer's updated at.
+ *     description: The customer's update date.
+ *   deleted_at:
+ *     type: string
+ *     format: date-time
+ *     title: deleted_at
+ *     description: The customer's deletion date.
  * 
 */
 

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

@@ -30,39 +30,39 @@
  *   address_name:
  *     type: string
  *     title: address_name
- *     description: The address's address name.
+ *     description: The address's name.
  *   is_default_shipping:
  *     type: boolean
  *     title: is_default_shipping
- *     description: The address's is default shipping.
+ *     description: Whether the address is the default shipping address.
  *   is_default_billing:
  *     type: boolean
  *     title: is_default_billing
- *     description: The address's is default billing.
+ *     description: Whether the address is the default billing address.
  *   customer_id:
  *     type: string
  *     title: customer_id
- *     description: The address's customer id.
+ *     description: The ID of the customer that this address belongs to.
  *   company:
  *     type: string
  *     title: company
- *     description: The address's company.
+ *     description: The customer's company.
  *   first_name:
  *     type: string
  *     title: first_name
- *     description: The address's first name.
+ *     description: The customer's first name.
  *   last_name:
  *     type: string
  *     title: last_name
- *     description: The address's last name.
+ *     description: The customer's last name.
  *   address_1:
  *     type: string
  *     title: address_1
- *     description: The address's address 1.
+ *     description: The address's first line.
  *   address_2:
  *     type: string
  *     title: address_2
- *     description: The address's address 2.
+ *     description: The address's second line.
  *   city:
  *     type: string
  *     title: city
@@ -71,6 +71,7 @@
  *     type: string
  *     title: country_code
  *     description: The address's country code.
+ *     example: us
  *   province:
  *     type: string
  *     title: province
@@ -85,17 +86,17 @@
  *     description: The address's phone.
  *   metadata:
  *     type: object
- *     description: The address's metadata.
+ *     description: The address's metadata, used to store custom key-value pairs.
  *   created_at:
  *     type: string
  *     format: date-time
  *     title: created_at
- *     description: The address's created at.
+ *     description: The address's creation date.
  *   updated_at:
  *     type: string
  *     format: date-time
  *     title: updated_at
- *     description: The address's updated at.
+ *     description: The address's update date.
  * 
 */
 

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

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

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

@@ -1,8 +1,42 @@
 /**
  * @schema AdminCustomerGroup
  * type: object
- * description: The group's groups.
+ * description: The customer group's details.
  * x-schemaName: AdminCustomerGroup
+ * required:
+ *   - id
+ *   - name
+ *   - customers
+ *   - metadata
+ *   - created_at
+ *   - updated_at
+ * properties:
+ *   id:
+ *     type: string
+ *     title: id
+ *     description: The customer group's ID.
+ *   name:
+ *     type: string
+ *     title: name
+ *     description: The customer group's name.
+ *   customers:
+ *     type: array
+ *     description: The customer group's customers.
+ *     items:
+ *       $ref: "#/components/schemas/BaseCustomer"
+ *   metadata:
+ *     type: object
+ *     description: The customer group's metadata, used to store custom key-value pairs.
+ *   created_at:
+ *     type: string
+ *     format: date-time
+ *     title: created_at
+ *     description: The customer group's creation date.
+ *   updated_at:
+ *     type: string
+ *     format: date-time
+ *     title: updated_at
+ *     description: The customer group's update date.
  * 
 */
 

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

@@ -0,0 +1,78 @@
+/**
+ * @schema BaseCustomer
+ * type: object
+ * description: The customer's details.
+ * x-schemaName: BaseCustomer
+ * required:
+ *   - id
+ *   - email
+ *   - default_billing_address_id
+ *   - default_shipping_address_id
+ *   - company_name
+ *   - first_name
+ *   - last_name
+ *   - addresses
+ * properties:
+ *   id:
+ *     type: string
+ *     title: id
+ *     description: The customer's ID.
+ *   email:
+ *     type: string
+ *     title: email
+ *     description: The customer's email.
+ *     format: email
+ *   default_billing_address_id:
+ *     type: string
+ *     title: default_billing_address_id
+ *     description: The ID of the address used as the default billing address.
+ *   default_shipping_address_id:
+ *     type: string
+ *     title: default_shipping_address_id
+ *     description: The ID of the address used as the default shipping address.
+ *   company_name:
+ *     type: string
+ *     title: company_name
+ *     description: The customer's company name.
+ *   first_name:
+ *     type: string
+ *     title: first_name
+ *     description: The customer's first name.
+ *   last_name:
+ *     type: string
+ *     title: last_name
+ *     description: The customer's last name.
+ *   addresses:
+ *     type: array
+ *     description: The customer's addresses.
+ *     items:
+ *       $ref: "#/components/schemas/BaseCustomerAddress"
+ *   phone:
+ *     type: string
+ *     title: phone
+ *     description: The customer's phone.
+ *   metadata:
+ *     type: object
+ *     description: The customer's metadata, used to store custom key-value pairs.
+ *   created_by:
+ *     type: string
+ *     title: created_by
+ *     description: The ID of the user that created this customer, if available.
+ *   created_at:
+ *     type: string
+ *     format: date-time
+ *     title: created_at
+ *     description: The customer's creation date.
+ *   updated_at:
+ *     type: string
+ *     format: date-time
+ *     title: updated_at
+ *     description: The customer's update date.
+ *   deleted_at:
+ *     type: string
+ *     format: date-time
+ *     title: deleted_at
+ *     description: The customer's deletion date.
+ * 
+*/
+