chore(oas): [12/n] improve oas schemas (#9200)

- improve OAS schemas [12/n]
- Support ignoring properties in type if it has the `@ignore` jsdoc tag.

www/utils/generated/oas-output/operations/admin/get_admin_promotions_rule-attribute-options_[rule_type].ts

@@ -2,16 +2,15 @@
  * @oas [get] /admin/promotions/rule-attribute-options/{rule_type}
  * operationId: GetPromotionsRuleAttributeOptionsRule_type
  * summary: List Rule Attribute Options of a Rule Type
- * x-sidebar-summary: List Rule Attribute Options
+ * x-sidebar-summary: List Potential Rule Attributes
- * description: >
+ * description: |
- *   Retrieve a list of attributes for the promotion and application method types specified in the query parameters.
+ *   Retrieve a list of potential rule attributes for the promotion and application method types specified in the query parameters.
- * 
  *   Only the attributes of the rule type specified in the path parameter are retrieved:
- * 
  *   - If `rule_type` is `rules`, the attributes of the promotion's type are retrieved.
  * 
- *   
+ *   - If `rule_type` is `target-rules`, the target rules' attributes of the application method's type are retrieved.
- *   - If `rule_type` is `target-rules`, the target rules' attributes of the application method's type are retrieved. - If `rule_type` is `buy-rules`, the buy rules' attributes of the application method's type are retrieved.
+ * 
+ *   - If `rule_type` is `buy-rules`, the buy rules' attributes of the application method's type are retrieved.
  * x-authenticated: true
  * parameters:
  *   - name: rule_type

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

@@ -4,86 +4,22 @@
  * description: The shipping option's details.
  * x-schemaName: AdminCreateShippingOption
  * required:
- *   - name
+ *   - label
- *   - service_zone_id
+ *   - description
- *   - shipping_profile_id
+ *   - code
- *   - price_type
- *   - provider_id
- *   - type
- *   - prices
  * properties:
- *   name:
+ *   label:
  *     type: string
- *     title: name
+ *     title: label
- *     description: The shipping option's name.
+ *     description: The type's label.
- *   service_zone_id:
+ *   description:
  *     type: string
- *     title: service_zone_id
+ *     title: description
- *     description: The ID of the service zone this shipping option belongs to.
+ *     description: The type's description.
- *   shipping_profile_id:
+ *   code:
  *     type: string
- *     title: shipping_profile_id
+ *     title: code
- *     description: The ID of the shipping profile this shipping option belongs to.
+ *     description: The type's code.
- *   data:
- *     type: object
- *     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 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 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. If `price_type` is `calculated`, pass an empty array for this property.
- *     items:
- *       oneOf:
- *         - type: object
- *           description: The price for a currency code.
- *           x-schemaName: AdminCreateShippingOptionPriceWithCurrency
- *           required:
- *             - currency_code
- *             - amount
- *           properties:
- *             currency_code:
- *               type: string
- *               title: currency_code
- *               description: The price's currency code.
- *             amount:
- *               type: number
- *               title: amount
- *               description: The price's amount.
- *         - type: object
- *           description: The price in a region.
- *           x-schemaName: AdminCreateShippingOptionPriceWithRegion
- *           required:
- *             - region_id
- *             - amount
- *           properties:
- *             region_id:
- *               type: string
- *               title: region_id
- *               description: The ID of the region this price is used in.
- *             amount:
- *               type: number
- *               title: amount
- *               description: The price's amount.
- *   rules:
- *     type: array
- *     description: The shipping option's rules.
- *     items:
- *       $ref: "#/components/schemas/AdminCreateShippingOptionRule"
  * 
 */
 

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

@@ -3,6 +3,18 @@
  * type: object
  * description: The shipping option's provider.
  * x-schemaName: AdminFulfillmentProvider
+ * required:
+ *   - id
+ *   - is_enabled
+ * properties:
+ *   id:
+ *     type: string
+ *     title: id
+ *     description: The provider's ID.
+ *   is_enabled:
+ *     type: boolean
+ *     title: is_enabled
+ *     description: The provider's is enabled.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminFulfillmentSet
  * type: object
- * description: The fulfillment set's parent.
+ * description: The service zone's fulfillment set.
  * x-schemaName: AdminFulfillmentSet
  * required:
  *   - id
@@ -16,37 +16,37 @@
  *   id:
  *     type: string
  *     title: id
- *     description: The parent's ID.
+ *     description: The fulfillment set's ID.
  *   name:
  *     type: string
  *     title: name
- *     description: The parent's name.
+ *     description: The fulfillment set's name.
  *   type:
  *     type: string
  *     title: type
- *     description: The parent's type.
+ *     description: The fulfillment set's type.
  *   location:
  *     $ref: "#/components/schemas/AdminStockLocation"
  *   service_zones:
  *     type: array
- *     description: The parent's service zones.
+ *     description: The fulfillment set's service zones.
  *     items:
  *       $ref: "#/components/schemas/AdminServiceZone"
  *   created_at:
  *     type: string
  *     format: date-time
  *     title: created_at
- *     description: The parent's created at.
+ *     description: The fulfillment set's created at.
  *   updated_at:
  *     type: string
  *     format: date-time
  *     title: updated_at
- *     description: The parent's updated at.
+ *     description: The fulfillment set's updated at.
  *   deleted_at:
  *     type: string
  *     format: date-time
  *     title: deleted_at
- *     description: The parent's deleted at.
+ *     description: The fulfillment set's deleted at.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminGeoZone
  * type: object
- * description: The geo zone's details.
+ * description: The geo zone's geo zones.
  * x-schemaName: AdminGeoZone
  * required:
  *   - id
@@ -45,17 +45,17 @@
  *     type: string
  *     format: date-time
  *     title: created_at
- *     description: The date the geo zone was created.
+ *     description: The geo zone's created at.
  *   updated_at:
  *     type: string
  *     format: date-time
  *     title: updated_at
- *     description: The date the geo zone was update.
+ *     description: The geo zone's updated at.
  *   deleted_at:
  *     type: string
  *     format: date-time
  *     title: deleted_at
- *     description: The date the geo zone was deleted.
+ *     description: The geo zone's deleted at.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminRuleAttributeOption
  * type: object
- * description: The attribute's attributes.
+ * description: The details of a potential rule attribute.
  * x-schemaName: AdminRuleAttributeOption
  * required:
  *   - id
@@ -9,33 +9,23 @@
  *   - label
  *   - field_type
  *   - required
- *   - disguised
  *   - operators
  * properties:
  *   id:
  *     type: string
  *     title: id
- *     description: The attribute's ID.
+ *     description: The rule attribute's ID, which is a rule's `attribute` it refers to.
+ *     example: "customer_group"
  *   value:
  *     type: string
  *     title: value
- *     description: The attribute's value.
+ *     description: The rule attribute's value.
+ *     example: "customer.groups.id"
  *   label:
  *     type: string
  *     title: label
- *     description: The attribute's label.
+ *     description: The rule attribute option's label.
- *   field_type:
+ *     example: "Customer Group"
- *     type: string
- *     title: field_type
- *     description: The attribute's field type.
- *   required:
- *     type: boolean
- *     title: required
- *     description: The attribute's required.
- *   disguised:
- *     type: boolean
- *     title: disguised
- *     description: The attribute's disguised.
  *   operators:
  *     type: array
  *     description: The attribute's operators.

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

@@ -1,25 +1,22 @@
 /**
  * @schema AdminRuleValueOption
  * type: object
- * description: The value's values.
+ * description: The details of a potential rule value.
  * x-schemaName: AdminRuleValueOption
  * required:
- *   - id
  *   - value
  *   - label
  * properties:
- *   id:
- *     type: string
- *     title: id
- *     description: The value's ID.
  *   value:
  *     type: string
  *     title: value
- *     description: The value's details.
+ *     description: The rule value's value.
+ *     example: "reg_123"
  *   label:
  *     type: string
  *     title: label
- *     description: The value's label.
+ *     description: The rule value's label.
+ *     example: "Europe Region"
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminSalesChannel
  * type: object
- * description: The order's sales channel.
+ * description: The sales channel's details.
  * x-schemaName: AdminSalesChannel
  * required:
  *   - id
@@ -28,25 +28,25 @@
  *   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, can hold custom key-value pairs.
  *   created_at:
  *     type: string
  *     format: date-time
  *     title: created_at
- *     description: The sales channel's created at.
+ *     description: The date the sales channel was created.
  *   updated_at:
  *     type: string
  *     format: date-time
  *     title: updated_at
- *     description: The sales channel's updated at.
+ *     description: The date the sales channel was updated.
  *   deleted_at:
  *     type: string
  *     format: date-time
  *     title: deleted_at
- *     description: The sales channel's deleted at.
+ *     description: The date the sales channel was deleted.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminSalesChannelDeleteResponse
  * type: object
- * description: SUMMARY
+ * description: The details of deleting a sales channel.
  * x-schemaName: AdminSalesChannelDeleteResponse
  * required:
  *   - id
@@ -20,7 +20,7 @@
  *   deleted:
  *     type: boolean
  *     title: deleted
- *     description: Whether the Sales Channel was deleted.
+ *     description: Whether the sales channel was deleted.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminSalesChannelResponse
  * type: object
- * description: SUMMARY
+ * description: The sales channel's details.
  * x-schemaName: AdminSalesChannelResponse
  * required:
  *   - sales_channel

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminServiceZone
  * type: object
- * description: The service zone's service zones.
+ * description: The shipping option's service zone.
  * x-schemaName: AdminServiceZone
  * required:
  *   - id

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminServiceZoneDeleteResponse
  * type: object
- * description: SUMMARY
+ * description: The details of the service zone deletion.
  * x-schemaName: AdminServiceZoneDeleteResponse
  * required:
  *   - id
@@ -11,15 +11,16 @@
  *   id:
  *     type: string
  *     title: id
- *     description: The fulfillment set's ID.
+ *     description: The service zone's ID.
  *   object:
  *     type: string
  *     title: object
  *     description: The name of the deleted object.
+ *     default: "service_zone"
  *   deleted:
  *     type: boolean
  *     title: deleted
- *     description: Whether the Fulfillment Set was deleted.
+ *     description: Whether the service zone was deleted.
  *   parent:
  *     $ref: "#/components/schemas/AdminFulfillmentSet"
  * 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminServiceZoneResponse
  * type: object
- * description: SUMMARY
+ * description: The service zone's details.
  * x-schemaName: AdminServiceZoneResponse
  * required:
  *   - service_zone

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

@@ -1,8 +1,99 @@
 /**
  * @schema AdminShippingOption
  * type: object
- * description: The shipping option's shipping options.
+ * description: The shipping option's details.
  * x-schemaName: AdminShippingOption
+ * required:
+ *   - id
+ *   - name
+ *   - price_type
+ *   - service_zone_id
+ *   - service_zone
+ *   - provider_id
+ *   - provider
+ *   - shipping_option_type_id
+ *   - type
+ *   - shipping_profile_id
+ *   - shipping_profile
+ *   - rules
+ *   - prices
+ *   - data
+ *   - metadata
+ *   - created_at
+ *   - updated_at
+ *   - deleted_at
+ * properties:
+ *   id:
+ *     type: string
+ *     title: id
+ *     description: The shipping option's ID.
+ *   name:
+ *     type: string
+ *     title: name
+ *     description: The shipping option's name.
+ *   price_type:
+ *     type: string
+ *     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:
+ *       - calculated
+ *       - flat
+ *   service_zone_id:
+ *     type: string
+ *     title: service_zone_id
+ *     description: The ID of the service zone this option belongs to.
+ *   service_zone:
+ *     $ref: "#/components/schemas/AdminServiceZone"
+ *   provider_id:
+ *     type: string
+ *     title: provider_id
+ *     description: The ID of the provider handling fulfillments created from this shipping option.
+ *   provider:
+ *     $ref: "#/components/schemas/AdminFulfillmentProvider"
+ *   shipping_option_type_id:
+ *     type: string
+ *     title: shipping_option_type_id
+ *     description: The ID of the associated shipping option type.
+ *   type:
+ *     $ref: "#/components/schemas/AdminShippingOption"
+ *   shipping_profile_id:
+ *     type: string
+ *     title: shipping_profile_id
+ *     description: The ID of the associated shipping profile.
+ *   shipping_profile:
+ *     $ref: "#/components/schemas/AdminShippingProfile"
+ *   rules:
+ *     type: array
+ *     description: The shipping option's rules.
+ *     items:
+ *       $ref: "#/components/schemas/AdminShippingOptionRule"
+ *   prices:
+ *     type: array
+ *     description: The shipping option's prices. If the `price_type` is `calculated`, this array will be empty since the price is calculated by the fulfillment provider during checkout.
+ *     items:
+ *       $ref: "#/components/schemas/AdminShippingOptionPrice"
+ *   data:
+ *     type: object
+ *     description: The shipping option's data, useful for the fulfillment provider handling fulfillments created from this option.
+ *     externalDocs:
+ *       url: https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/shipping-option#data-property
+ *   metadata:
+ *     type: object
+ *     description: The shipping option's metadata, can hold custom key-value pairs.
+ *   created_at:
+ *     type: string
+ *     format: date-time
+ *     title: created_at
+ *     description: The date the shipping option was created.
+ *   updated_at:
+ *     type: string
+ *     format: date-time
+ *     title: updated_at
+ *     description: The date the shipping option was updated.
+ *   deleted_at:
+ *     type: string
+ *     format: date-time
+ *     title: deleted_at
+ *     description: The date the shipping option was deleted.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminShippingOptionDeleteResponse
  * type: object
- * description: SUMMARY
+ * description: The details of the shipping option's deletion.
  * x-schemaName: AdminShippingOptionDeleteResponse
  * required:
  *   - id
@@ -20,7 +20,7 @@
  *   deleted:
  *     type: boolean
  *     title: deleted
- *     description: Whether the Shipping Option was deleted.
+ *     description: Whether the shipping option was deleted.
  * 
 */
 

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

@@ -0,0 +1,79 @@
+/**
+ * @schema AdminShippingOptionPrice
+ * type: object
+ * description: The details of the shipping option's price.
+ * x-schemaName: AdminShippingOptionPrice
+ * required:
+ *   - price_rules
+ *   - rules_count
+ *   - id
+ *   - title
+ *   - currency_code
+ *   - amount
+ *   - raw_amount
+ *   - min_quantity
+ *   - max_quantity
+ *   - price_set_id
+ *   - created_at
+ *   - updated_at
+ *   - deleted_at
+ * properties:
+ *   price_rules:
+ *     type: array
+ *     description: The price's rules.
+ *     items:
+ *       $ref: "#/components/schemas/AdminShippingOptionPriceRule"
+ *   rules_count:
+ *     type: number
+ *     title: rules_count
+ *     description: The number of rules the price has.
+ *   id:
+ *     type: string
+ *     title: id
+ *     description: The price's ID.
+ *   title:
+ *     type: string
+ *     title: title
+ *     description: The price's title.
+ *   currency_code:
+ *     type: string
+ *     title: currency_code
+ *     description: The price's currency code.
+ *     example: usd
+ *   amount:
+ *     type: number
+ *     title: amount
+ *     description: The price's amount.
+ *   raw_amount:
+ *     type: object
+ *     description: The price's raw amount.
+ *   min_quantity:
+ *     type: number
+ *     title: min_quantity
+ *     description: The minimum quantity required in the cart for this price to apply.
+ *   max_quantity:
+ *     type: number
+ *     title: max_quantity
+ *     description: The maximum quantity that the cart's items must not surpass for this price to apply.
+ *   price_set_id:
+ *     type: string
+ *     title: price_set_id
+ *     description: The ID of the price set this price belongs to.
+ *   created_at:
+ *     type: string
+ *     format: date-time
+ *     title: created_at
+ *     description: The date the price was created.
+ *   updated_at:
+ *     type: string
+ *     format: date-time
+ *     title: updated_at
+ *     description: The date the price was updated.
+ *   deleted_at:
+ *     type: string
+ *     format: date-time
+ *     title: deleted_at
+ *     description: The date the price was deleted.
+ * 
+*/
+

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

@@ -0,0 +1,20 @@
+/**
+ * @schema AdminShippingOptionPriceRule
+ * type: object
+ * description: The details of a shipping option price's rule.
+ * x-schemaName: AdminShippingOptionPriceRule
+ * required:
+ *   - id
+ *   - value
+ * properties:
+ *   id:
+ *     type: string
+ *     title: id
+ *     description: The price rule's ID.
+ *   value:
+ *     type: string
+ *     title: value
+ *     description: The price rule's value.
+ * 
+*/
+

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminShippingOptionResponse
  * type: object
- * description: SUMMARY
+ * description: The shipping option's details.
  * x-schemaName: AdminShippingOptionResponse
  * required:
  *   - shipping_option

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminShippingOptionRule
  * type: object
- * description: The updated's details.
+ * description: The shipping option rule's details.
  * x-schemaName: AdminShippingOptionRule
  * required:
  *   - id
@@ -16,45 +16,49 @@
  *   id:
  *     type: string
  *     title: id
- *     description: The updated's ID.
+ *     description: The shipping option rule's ID.
  *   attribute:
  *     type: string
  *     title: attribute
- *     description: The updated's attribute.
+ *     description: The shipping option rule's attribute.
+ *     example: is_return
  *   operator:
  *     type: string
  *     title: operator
- *     description: The updated's operator.
+ *     description: The shipping option rule's operator.
+ *     example: eq
  *   value:
  *     oneOf:
  *       - type: string
  *         title: value
- *         description: The updated's value.
+ *         description: The rule's value.
+ *         example: '"true"'
  *       - type: array
- *         description: The updated's value.
+ *         description: The rule's values.
  *         items:
  *           type: string
  *           title: value
- *           description: The value's details.
+ *           description: A rule's value
+ *           example: '"true"'
  *   shipping_option_id:
  *     type: string
  *     title: shipping_option_id
- *     description: The updated's shipping option id.
+ *     description: The ID of the shipping option this rule is for.
  *   created_at:
  *     type: string
  *     format: date-time
  *     title: created_at
- *     description: The updated's created at.
+ *     description: The date the shipping option rule was created.
  *   updated_at:
  *     type: string
  *     format: date-time
  *     title: updated_at
- *     description: The updated's updated at.
+ *     description: The date the shipping option rule was updated.
  *   deleted_at:
  *     type: string
  *     format: date-time
  *     title: deleted_at
- *     description: The updated's deleted at.
+ *     description: The date the shipping option rule was deleted.
  * 
 */
 

www/utils/packages/docs-generator/src/classes/kinds/oas.ts

@@ -1543,6 +1543,15 @@ class OasKindGenerator extends FunctionKindGenerator {
             ) {
               return
             }
+
+            const shouldIgnore = property
+              .getJsDocTags()
+              .some((tag) => tag.name === "ignore")
+
+            if (shouldIgnore) {
+              return
+            }
+
             if (this.isRequired(property)) {
               requiredProperties.push(property.name)
             }