oas: [15/n] improve oas schemas

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

@@ -56,7 +56,7 @@
  *     type: array
  *     description: The customer's addresses.
  *     items:
- *       $ref: "#/components/schemas/BaseCustomerAddress"
+ *       $ref: "#/components/schemas/AdminCustomerAddress"
  *   phone:
  *     type: string
  *     title: phone

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

@@ -23,7 +23,7 @@
  *     type: array
  *     description: The customer group's customers.
  *     items:
- *       $ref: "#/components/schemas/BaseCustomer"
+ *       $ref: "#/components/schemas/AdminCustomer"
  *   metadata:
  *     type: object
  *     description: The customer group's metadata, used to store custom key-value pairs.

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

@@ -120,7 +120,7 @@
  *               title: variant_id
  *               description: The ID of the associated variant.
  *             product:
- *               $ref: "#/components/schemas/BaseProduct"
+ *               $ref: "#/components/schemas/AdminProduct"
  *             product_id:
  *               type: string
  *               title: product_id

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

@@ -16,7 +16,7 @@
  *     title: title
  *     description: The product option's title.
  *   product:
- *     $ref: "#/components/schemas/BaseProduct"
+ *     $ref: "#/components/schemas/AdminProduct"
  *   product_id:
  *     type: string
  *     title: product_id

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

@@ -109,7 +109,7 @@
  *     items:
  *       $ref: "#/components/schemas/BaseProductOptionValue"
  *   product:
- *     $ref: "#/components/schemas/BaseProduct"
+ *     $ref: "#/components/schemas/AdminProduct"
  *   product_id:
  *     type: string
  *     title: product_id

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminWorkflowExecutionResponse
  * type: object
- * description: SUMMARY
+ * description: The workflow execution's details.
  * x-schemaName: AdminWorkflowExecutionResponse
  * required:
  *   - workflow_execution

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

@@ -1,7 +1,7 @@
 /**
  * @schema ApiKeyResponse
  * type: object
- * description: The api key's details.
+ * description: The API key's details.
  * x-schemaName: ApiKeyResponse
  * required:
  *   - id
@@ -18,46 +18,47 @@
  *   id:
  *     type: string
  *     title: id
- *     description: The api key's ID.
+ *     description: The API key's ID.
  *   token:
  *     type: string
  *     title: token
- *     description: The api key's token.
+ *     description: The API key's token.
  *   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. For example `sk_...123`.
  *   title:
  *     type: string
  *     title: title
- *     description: The api key's title.
+ *     description: The API key's title.
  *   type:
  *     type: string
+ *     description: The API key's type. `secret` API keys are used for authenticating admin users, and `publishable` API key are used for storefronts and similar clients to scope requests to sales channels.
  *     enum:
  *       - secret
  *       - publishable
  *   last_used_at:
  *     type: string
  *     title: last_used_at
- *     description: The api key's last used at.
+ *     description: The date 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.
  *   created_at:
  *     type: string
  *     title: created_at
- *     description: The api key's created at.
+ *     description: The date the API key was created.
  *     format: date-time
  *   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.
  *   revoked_at:
  *     type: string
  *     title: revoked_at
- *     description: The api key's revoked at.
+ *     description: The date the API key was revoked.
  *     format: date-time
  * 
 */

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

@@ -1,7 +1,7 @@
 /**
  * @schema BaseApplicationMethod
  * type: object
- * description: The promotion's application method.
+ * description: The application method's details.
  * x-schemaName: BaseApplicationMethod
  * required:
  *   - id
@@ -12,53 +12,54 @@
  *     description: The application method's ID.
  *   type:
  *     type: string
- *     description: The application method's type.
+ *     description: How the associated promotion is applied. `fixed` means a fixed amount is discounted; `percentage` means a percentage of the original amount is discounted.
  *     enum:
  *       - fixed
  *       - percentage
  *   target_type:
  *     type: string
- *     description: The application method's target type.
+ *     description: Which item does the promotion apply to. `items` mean the promotion applies to the cart's items; `shipping_methods` means the promotion applies to the cart's shipping methods; `order` means the promotion applies on the entire order.
  *     enum:
  *       - items
  *       - shipping_methods
  *       - order
  *   allocation:
  *     type: string
- *     description: The application method's allocation.
+ *     description: How is the promotion amount discounted. `each` means the discounted amount is applied on each applicable item; `across` means the discounted amount is split accross the applicable items.
  *     enum:
  *       - each
  *       - across
  *   value:
  *     type: number
  *     title: value
- *     description: The application method's value.
+ *     description: The amount to be discounted.
  *   currency_code:
  *     type: string
  *     title: currency_code
  *     description: The application method's currency code.
+ *     example: usd
  *   max_quantity:
  *     type: number
  *     title: max_quantity
- *     description: The application method's max quantity.
+ *     description: The max quantity allowed in the cart for the associated promotion to be applied.
  *   buy_rules_min_quantity:
  *     type: number
  *     title: buy_rules_min_quantity
- *     description: The application method's buy rules min quantity.
+ *     description: The minimum quantity required for a `buyget` promotion to be applied. For example, if the promotion is a "Buy 2 shirts get 1 free", the value of this attribute is `2`.
  *   apply_to_quantity:
  *     type: number
  *     title: apply_to_quantity
- *     description: The application method's apply to quantity.
+ *     description: The quantity that results from matching the `buyget` promotion's condition. For example, if the promotion is a "Buy 2 shirts get 1 free", the value of this attribute is `1`.
  *   promotion:
  *     $ref: "#/components/schemas/BasePromotion"
  *   target_rules:
  *     type: array
- *     description: The application method's target rules.
+ *     description: The application method's target rules. These rules indicate which items / shipping methods the promotion applies to.
  *     items:
  *       $ref: "#/components/schemas/BasePromotionRule"
  *   buy_rules:
  *     type: array
- *     description: The application method's buy rules.
+ *     description: The application method's buy rules. These rules indicate which items are part of the "Buy X" rule.
  *     items:
  *       $ref: "#/components/schemas/BasePromotionRule"
  * 

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

@@ -1,8 +1,33 @@
 /**
  * @schema BaseCapture
  * type: object
- * description: The capture's captures.
+ * description: The details of a captured payment.
  * x-schemaName: BaseCapture
+ * required:
+ *   - id
+ *   - amount
+ *   - created_at
+ *   - payment
+ * properties:
+ *   id:
+ *     type: string
+ *     title: id
+ *     description: The payment capture's ID.
+ *   amount:
+ *     type: number
+ *     title: amount
+ *     description: The captured amount.
+ *   created_at:
+ *     type: string
+ *     format: date-time
+ *     title: created_at
+ *     description: The date the capture was created.
+ *   created_by:
+ *     type: string
+ *     title: created_by
+ *     description: The ID of the user that captured the payment.
+ *   payment:
+ *     $ref: "#/components/schemas/BasePayment"
  * 
 */