chore(oas): [10/n] improve oas schemas (#9167)

* chore(oas): [10/n] improve oas schemas * fix validation error --------- Co-authored-by: Oli Juhl <59018053+olivermrbl@users.noreply.github.com>
2024-09-19 18:51:55 +02:00
1 parent 230a16ac5c
commit d6ce0688db
@@ -1,7 +1,7 @@
 /**
 * @schema AdminProductOption
 * type: object
- * description: The product's product option.
+ * description: The product option's details.
 * x-schemaName: AdminProductOption
 * required:
 *   - id
@@ -20,7 +20,7 @@
 *   product_id:
 *     type: string
 *     title: product_id
- *     description: The product option's product id.
+ *     description: The ID of the product this option belongs to.
 *   values:
 *     type: array
 *     description: The product option's values.
@@ -28,22 +28,22 @@
 *       $ref: "#/components/schemas/BaseProductOptionValue"
 *   metadata:
 *     type: object
- *     description: The product option's metadata.
+ *     description: The product option's metadata, can hold custom key-value pairs.
 *   created_at:
 *     type: string
 *     format: date-time
 *     title: created_at
- *     description: The product option's created at.
+ *     description: The date the product option was created.
 *   updated_at:
 *     type: string
 *     format: date-time
 *     title: updated_at
- *     description: The product option's updated at.
+ *     description: The date the product option was updated.
 *   deleted_at:
 *     type: string
 *     format: date-time
 *     title: deleted_at
- *     description: The product option's deleted at.
+ *     description: The date the product option was deleted.
 * 
 */
@@ -1,7 +1,7 @@
 /**
 * @schema AdminProductOptionDeleteResponse
 * type: object
- * description: SUMMARY
+ * description: The details of the product option deletion.
 * x-schemaName: AdminProductOptionDeleteResponse
 * required:
 *   - id
@@ -11,15 +11,16 @@
 *   id:
 *     type: string
 *     title: id
- *     description: The product's ID.
+ *     description: The product option's ID.
 *   object:
 *     type: string
 *     title: object
 *     description: The name of the deleted object.
 *     default: "product_option"
 *   deleted:
 *     type: boolean
 *     title: deleted
- *     description: Whether the Product was deleted.
+ *     description: Whether the product option was deleted.
 *   parent:
 *     $ref: "#/components/schemas/AdminProduct"
 * 
@@ -1,7 +1,7 @@
 /**
 * @schema AdminProductOptionResponse
 * type: object
- * description: SUMMARY
+ * description: The product option's details.
 * x-schemaName: AdminProductOptionResponse
 * required:
 *   - product_option
@@ -1,7 +1,7 @@
 /**
 * @schema AdminProductResponse
 * type: object
- * description: SUMMARY
+ * description: The product's details.
 * x-schemaName: AdminProductResponse
 * required:
 *   - product
@@ -1,7 +1,7 @@
 /**
 * @schema AdminProductTag
 * type: object
- * description: The tag's tags.
+ * description: The product tag's details.
 * x-schemaName: AdminProductTag
 * required:
 *   - id
@@ -21,20 +21,20 @@
 *     type: string
 *     format: date-time
 *     title: created_at
- *     description: The tag's created at.
+ *     description: The date the tag was created.
 *   updated_at:
 *     type: string
 *     format: date-time
 *     title: updated_at
- *     description: The tag's updated at.
+ *     description: The date the tag was updated.
 *   deleted_at:
 *     type: string
 *     format: date-time
 *     title: deleted_at
- *     description: The tag's deleted at.
+ *     description: The date the tag was deleted.
 *   metadata:
 *     type: object
- *     description: The tag's metadata.
+ *     description: The tag's metadata, can hold custom key-value pairs.
 * 
 */
@@ -1,7 +1,7 @@
 /**
 * @schema AdminProductTagDeleteResponse
 * type: object
- * description: SUMMARY
+ * description: The details of the product tag deletion.
 * x-schemaName: AdminProductTagDeleteResponse
 * required:
 *   - id
@@ -20,7 +20,7 @@
 *   deleted:
 *     type: boolean
 *     title: deleted
- *     description: Whether the Product Tag was deleted.
+ *     description: Whether the product tag was deleted.
 * 
 */
@@ -1,7 +1,7 @@
 /**
 * @schema AdminProductTagListResponse
 * type: object
- * description: SUMMARY
+ * description: The paginated list of product tags.
 * x-schemaName: AdminProductTagListResponse
 * required:
 *   - limit
@@ -12,18 +12,18 @@
 *   limit:
 *     type: number
 *     title: limit
- *     description: The product tag's limit.
+ *     description: The maximum number of items returned.
 *   offset:
 *     type: number
 *     title: offset
- *     description: The product tag's offset.
+ *     description: The number of items skipped before retrieving the returned items.
 *   count:
 *     type: number
 *     title: count
- *     description: The product tag's count.
+ *     description: The total number of items.
 *   product_tags:
 *     type: array
- *     description: The product tag's product tags.
+ *     description: The list of product tags.
 *     items:
 *       $ref: "#/components/schemas/AdminProductTag"
 * 
@@ -1,7 +1,7 @@
 /**
 * @schema AdminProductTagResponse
 * type: object
- * description: SUMMARY
+ * description: The product tag's details.
 * x-schemaName: AdminProductTagResponse
 * required:
 *   - product_tag
@@ -1,7 +1,7 @@
 /**
 * @schema AdminProductType
 * type: object
- * description: The parent's type.
+ * description: The product type's details.
 * x-schemaName: AdminProductType
 * required:
 *   - id
@@ -21,20 +21,20 @@
 *     type: string
 *     format: date-time
 *     title: created_at
- *     description: The type's created at.
+ *     description: The date the type was created.
 *   updated_at:
 *     type: string
 *     format: date-time
 *     title: updated_at
- *     description: The type's updated at.
+ *     description: The date the type was updated.
 *   deleted_at:
 *     type: string
 *     format: date-time
 *     title: deleted_at
- *     description: The type's deleted at.
+ *     description: The date the type was deleted.
 *   metadata:
 *     type: object
- *     description: The type's metadata.
+ *     description: The type's metadata, can hold custom key-value pairs.
 * 
 */
@@ -1,7 +1,7 @@
 /**
 * @schema AdminProductTypeDeleteResponse
 * type: object
- * description: SUMMARY
+ * description: The details of the product type deletion.
 * x-schemaName: AdminProductTypeDeleteResponse
 * required:
 *   - id
@@ -20,7 +20,7 @@
 *   deleted:
 *     type: boolean
 *     title: deleted
- *     description: Whether the Product Type was deleted.
+ *     description: Whether the product type was deleted.
 * 
 */
@@ -1,7 +1,7 @@
 /**
 * @schema AdminProductTypeListResponse
 * type: object
- * description: SUMMARY
+ * description: The paginated list of product types.
 * x-schemaName: AdminProductTypeListResponse
 * required:
 *   - limit
@@ -12,18 +12,18 @@
 *   limit:
 *     type: number
 *     title: limit
- *     description: The product type's limit.
+ *     description: The maximum number of items returned.
 *   offset:
 *     type: number
 *     title: offset
- *     description: The product type's offset.
+ *     description: The number of items skipped before retrieving the returned items.
 *   count:
 *     type: number
 *     title: count
- *     description: The product type's count.
+ *     description: The total number of items.
 *   product_types:
 *     type: array
- *     description: The product type's product types.
+ *     description: The list of product types.
 *     items:
 *       $ref: "#/components/schemas/AdminProductType"
 * 
@@ -1,7 +1,7 @@
 /**
 * @schema AdminProductTypeResponse
 * type: object
- * description: SUMMARY
+ * description: The product type's details.
 * x-schemaName: AdminProductTypeResponse
 * required:
 *   - product_type
@@ -1,7 +1,7 @@
 /**
 * @schema AdminProductVariant
 * type: object
- * description: The product's parent.
+ * description: The product variant's details.
 * x-schemaName: AdminProductVariant
 * required:
 *   - prices
@@ -28,84 +28,84 @@
 * properties:
 *   prices:
 *     type: array
- *     description: The parent's prices.
+ *     description: The variant's prices.
 *     items:
 *       $ref: "#/components/schemas/AdminPrice"
 *   id:
 *     type: string
 *     title: id
- *     description: The parent's ID.
+ *     description: The variant's ID.
 *   title:
 *     type: string
 *     title: title
- *     description: The parent's title.
+ *     description: The variant's title.
 *   sku:
 *     type: string
 *     title: sku
- *     description: The parent's sku.
+ *     description: The variant's SKU.
 *   barcode:
 *     type: string
 *     title: barcode
- *     description: The parent's barcode.
+ *     description: The variant's barcode.
 *   ean:
 *     type: string
 *     title: ean
- *     description: The parent's ean.
+ *     description: The variant's EAN code.
 *   upc:
 *     type: string
 *     title: upc
- *     description: The parent's upc.
+ *     description: The variant's UPC.
 *   allow_backorder:
 *     type: boolean
 *     title: allow_backorder
- *     description: The parent's allow backorder.
+ *     description: Whether the variant can be ordered even if it's out of stock.
 *   manage_inventory:
 *     type: boolean
 *     title: manage_inventory
- *     description: The parent's manage inventory.
+ *     description: Whether the Medusa application manages the variant's inventory quantity and availablility. If disabled, the variant is always considered in stock.
 *   inventory_quantity:
 *     type: number
 *     title: inventory_quantity
- *     description: The parent's inventory quantity.
+ *     description: The variant's inventory quantity. This is only included if you pass in the `fields` query parameter a `+variants.inventory_quantity` parameter.
 *   hs_code:
 *     type: string
 *     title: hs_code
- *     description: The parent's hs code.
+ *     description: The variant's HS code.
 *   origin_country:
 *     type: string
 *     title: origin_country
- *     description: The parent's origin country.
+ *     description: The variant's origin country.
 *   mid_code:
 *     type: string
 *     title: mid_code
- *     description: The parent's mid code.
+ *     description: The variant's MID code.
 *   material:
 *     type: string
 *     title: material
- *     description: The parent's material.
+ *     description: The variant's material.
 *   weight:
 *     type: number
 *     title: weight
- *     description: The parent's weight.
+ *     description: The variant's weight.
 *   length:
 *     type: number
 *     title: length
- *     description: The parent's length.
+ *     description: The variant's length.
 *   height:
 *     type: number
 *     title: height
- *     description: The parent's height.
+ *     description: The variant's height.
 *   width:
 *     type: number
 *     title: width
- *     description: The parent's width.
+ *     description: The variant's width.
 *   variant_rank:
 *     type: number
 *     title: variant_rank
- *     description: The parent's variant rank.
+ *     description: The variant's rank among its sibling variants.
 *   options:
 *     type: array
- *     description: The parent's options.
+ *     description: The variant's option values.
 *     items:
 *       $ref: "#/components/schemas/BaseProductOptionValue"
 *   product:
@@ -113,27 +113,27 @@
 *   product_id:
 *     type: string
 *     title: product_id
- *     description: The parent's product id.
+ *     description: The ID of the product that the variant belongs to.
 *   calculated_price:
 *     $ref: "#/components/schemas/BaseCalculatedPriceSet"
 *   created_at:
 *     type: string
 *     format: date-time
 *     title: created_at
- *     description: The parent's created at.
+ *     description: The date the variant was created.
 *   updated_at:
 *     type: string
 *     format: date-time
 *     title: updated_at
- *     description: The parent's updated at.
+ *     description: The date the variant was updated.
 *   deleted_at:
 *     type: string
 *     format: date-time
 *     title: deleted_at
- *     description: The parent's deleted at.
+ *     description: The date the variant was deleted.
 *   metadata:
 *     type: object
- *     description: The parent's metadata.
+ *     description: The variant's metadata, can hold custom key-value pairs.
 * 
 */
@@ -1,7 +1,7 @@
 /**
 * @schema AdminProductVariantDeleteResponse
 * type: object
- * description: SUMMARY
+ * description: The details of the product variant's deletion.
 * x-schemaName: AdminProductVariantDeleteResponse
 * required:
 *   - id
@@ -11,7 +11,7 @@
 *   id:
 *     type: string
 *     title: id
- *     description: The product's ID.
+ *     description: The product variant's ID.
 *   object:
 *     type: string
 *     title: object
@@ -19,7 +19,8 @@
 *   deleted:
 *     type: boolean
 *     title: deleted
- *     description: Whether the Product was deleted.
+ *     description: Whether the product variant was deleted.
 *     default: "variant"
 *   parent:
 *     $ref: "#/components/schemas/AdminProduct"
 * 
@@ -1,7 +1,7 @@
 /**
 * @schema AdminProductVariantInventoryBatchResponse
 * type: object
- * description: SUMMARY
+ * description: The created, updated, and deleted associations between variants and inventory items.
 * x-schemaName: AdminProductVariantInventoryBatchResponse
 * required:
 *   - created
@@ -12,10 +12,10 @@
 *     oneOf:
 *       - $ref: "#/components/schemas/AdminProductVariantInventoryLink"
 *       - type: array
- *         description: The product's created.
+ *         description: The created associations between product variants and inventory items.
 *         items:
 *           type: object
- *           description: The created's details.
+ *           description: A created association between a product variant and an inventory item.
 *           x-schemaName: AdminProductVariantInventoryLink
 *           required:
 *             - productService
@@ -23,32 +23,32 @@
 *           properties:
 *             productService:
 *               type: object
- *               description: The created's productservice.
+ *               description: The product variant's details.
 *               required:
 *                 - variant_id
 *               properties:
 *                 variant_id:
 *                   type: string
 *                   title: variant_id
- *                   description: The productservice's variant id.
+ *                   description: The ID of the product variant.
 *             inventoryService:
 *               type: object
- *               description: The created's inventoryservice.
+ *               description: The inventory item's details.
 *               required:
 *                 - inventory_item_id
 *               properties:
 *                 inventory_item_id:
 *                   type: string
 *                   title: inventory_item_id
- *                   description: The inventoryservice's inventory item id.
+ *                   description: The ID of the inventory item.
 *   updated:
 *     oneOf:
 *       - $ref: "#/components/schemas/AdminProductVariantInventoryLink"
 *       - type: array
- *         description: The product's updated.
+ *         description: The updated associations between product variants and inventory items.
 *         items:
 *           type: object
- *           description: The updated's details.
+ *           description: An updated association between a product variant and an inventory item.
 *           x-schemaName: AdminProductVariantInventoryLink
 *           required:
 *             - productService
@@ -56,32 +56,32 @@
 *           properties:
 *             productService:
 *               type: object
- *               description: The updated's productservice.
+ *               description: The product variant's details.
 *               required:
 *                 - variant_id
 *               properties:
 *                 variant_id:
 *                   type: string
 *                   title: variant_id
- *                   description: The productservice's variant id.
+ *                   description: The ID of the product variant.
 *             inventoryService:
 *               type: object
- *               description: The updated's inventoryservice.
+ *               description: The inventory item's details.
 *               required:
 *                 - inventory_item_id
 *               properties:
 *                 inventory_item_id:
 *                   type: string
 *                   title: inventory_item_id
- *                   description: The inventoryservice's inventory item id.
+ *                   description: The ID of the inventory item.
 *   deleted:
 *     oneOf:
 *       - $ref: "#/components/schemas/AdminProductVariantInventoryLink"
 *       - type: array
- *         description: SUMMARY
+ *         description: The deleted associations between product variants and inventory items.
 *         items:
 *           type: object
- *           description: SUMMARY
+ *           description: An deleted association between a product variant and an inventory item.
 *           x-schemaName: AdminProductVariantInventoryLink
 *           required:
 *             - productService
@@ -89,24 +89,24 @@
 *           properties:
 *             productService:
 *               type: object
- *               description: The deleted's productservice.
+ *               description: The product variant's details.
 *               required:
 *                 - variant_id
 *               properties:
 *                 variant_id:
 *                   type: string
 *                   title: variant_id
- *                   description: The productservice's variant id.
+ *                   description: The ID of the product variant.
 *             inventoryService:
 *               type: object
- *               description: The deleted's inventoryservice.
+ *               description: The inventory item's details.
 *               required:
 *                 - inventory_item_id
 *               properties:
 *                 inventory_item_id:
 *                   type: string
 *                   title: inventory_item_id
- *                   description: The inventoryservice's inventory item id.
+ *                   description: The ID of the inventory item.
 * 
 */
@@ -1,7 +1,7 @@
 /**
 * @schema AdminProductVariantInventoryLink
 * type: object
- * description: The product's ID.
+ * description: The details of an association between a product variant and an inventory item.
 * x-schemaName: AdminProductVariantInventoryLink
 * required:
 *   - productService
@@ -9,24 +9,24 @@
 * properties:
 *   productService:
 *     type: object
- *     description: The id's productservice.
+ *     description: The product variant's details.
 *     required:
 *       - variant_id
 *     properties:
 *       variant_id:
 *         type: string
 *         title: variant_id
- *         description: The productservice's variant id.
+ *         description: The ID of the product variant.
 *   inventoryService:
 *     type: object
- *     description: The id's inventoryservice.
+ *     description: The inventory item's details.
 *     required:
 *       - inventory_item_id
 *     properties:
 *       inventory_item_id:
 *         type: string
 *         title: inventory_item_id
- *         description: The inventoryservice's inventory item id.
+ *         description: The ID of the inventory item.
 * 
 */
@@ -1,7 +1,7 @@
 /**
 * @schema AdminProductVariantInventoryLinkDeleteResponse
 * type: object
- * description: SUMMARY
+ * description: The details of the deleted associated between a product variant and an inventory item.
 * x-schemaName: AdminProductVariantInventoryLinkDeleteResponse
 * required:
 *   - id
@@ -15,10 +15,11 @@
 *     type: string
 *     title: object
 *     description: The name of the deleted object.
 *     default: "variant-inventory-item-link"
 *   deleted:
 *     type: boolean
 *     title: deleted
- *     description: Whether the Product was deleted.
+ *     description: Whether the association was deleted.
 *   parent:
 *     $ref: "#/components/schemas/AdminProductVariant"
 *