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

Improve oas schemas [3/n]
2024-09-07 06:16:00 +00:00
parent a7180e29b8
commit 4b8d9cc735
20 changed files with 285 additions and 97 deletions
@@ -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