oas: [5/n] improve oas schemas (#9066)

Improve oas schemas [5/n]

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminFulfillmentProvider
  * type: object
- * description: The fulfillment provider's fulfillment providers.
+ * description: The shipping option's provider.
  * x-schemaName: AdminFulfillmentProvider
  * 
 */

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

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

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminFulfillmentResponse
  * type: object
- * description: SUMMARY
+ * description: A fulfillment's details.
  * x-schemaName: AdminFulfillmentResponse
  * required:
  *   - fulfillment

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminFulfillmentSetDeleteResponse
  * type: object
- * description: SUMMARY
+ * description: The deletion details.
  * x-schemaName: AdminFulfillmentSetDeleteResponse
  * required:
  *   - id
@@ -20,7 +20,7 @@
  *   deleted:
  *     type: boolean
  *     title: deleted
- *     description: Whether the Fulfillment Set was deleted.
+ *     description: Whether the fulfillment set was deleted.
  * 
 */
 

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

@@ -1,8 +1,61 @@
 /**
  * @schema AdminGeoZone
  * type: object
- * description: The geo zone's geo zones.
+ * description: The geo zone's details.
  * x-schemaName: AdminGeoZone
+ * required:
+ *   - id
+ *   - type
+ *   - country_code
+ *   - province_code
+ *   - city
+ *   - postal_expression
+ *   - created_at
+ *   - updated_at
+ *   - deleted_at
+ * properties:
+ *   id:
+ *     type: string
+ *     title: id
+ *     description: The geo zone's ID.
+ *   type:
+ *     type: string
+ *     description: The geo zone's type.
+ *     enum:
+ *       - country
+ *       - province
+ *       - city
+ *       - zip
+ *   country_code:
+ *     type: string
+ *     title: country_code
+ *     description: The geo zone's country code.
+ *   province_code:
+ *     type: string
+ *     title: province_code
+ *     description: The geo zone's province code.
+ *   city:
+ *     type: string
+ *     title: city
+ *     description: The geo zone's city.
+ *   postal_expression:
+ *     type: object
+ *     description: The geo zone's postal expression.
+ *   created_at:
+ *     type: string
+ *     format: date-time
+ *     title: created_at
+ *     description: The date the geo zone was created.
+ *   updated_at:
+ *     type: string
+ *     format: date-time
+ *     title: updated_at
+ *     description: The date the geo zone was update.
+ *   deleted_at:
+ *     type: string
+ *     format: date-time
+ *     title: deleted_at
+ *     description: The date the geo zone was deleted.
  * 
 */
 

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

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

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminImportProductResponse
  * type: object
- * description: SUMMARY
+ * description: The import process's details.
  * x-schemaName: AdminImportProductResponse
  * required:
  *   - transaction_id
@@ -10,10 +10,10 @@
  *   transaction_id:
  *     type: string
  *     title: transaction_id
- *     description: The product's transaction id.
+ *     description: The ID of the workflow execution's transaction. This is useful to confirm the import using the `/admin/products/:transaction-id/import` API route.
  *   summary:
  *     type: object
- *     description: The product's summary.
+ *     description: The import's summary.
  *     required:
  *       - toCreate
  *       - toUpdate
@@ -21,11 +21,11 @@
  *       toCreate:
  *         type: number
  *         title: toCreate
- *         description: The summary's tocreate.
+ *         description: The number of products that will be created by this import.
  *       toUpdate:
  *         type: number
  *         title: toUpdate
- *         description: The summary's toupdate.
+ *         description: The number of products that will be updated by this import.
  * 
 */
 

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

@@ -14,7 +14,7 @@
  *   sku:
  *     type: string
  *     title: sku
- *     description: The inventory item's sku.
+ *     description: The inventory item's SKU.
  *   origin_country:
  *     type: string
  *     title: origin_country
@@ -22,15 +22,15 @@
  *   hs_code:
  *     type: string
  *     title: hs_code
- *     description: The inventory item's hs code.
+ *     description: The inventory item's HS code.
  *   requires_shipping:
  *     type: boolean
  *     title: requires_shipping
- *     description: The inventory item's requires shipping.
+ *     description: Whether the inventory item requires shipping.
  *   mid_code:
  *     type: string
  *     title: mid_code
- *     description: The inventory item's mid code.
+ *     description: The inventory item's MID code.
  *   material:
  *     type: string
  *     title: material
@@ -62,13 +62,13 @@
  *   thumbnail:
  *     type: string
  *     title: thumbnail
- *     description: The inventory item's thumbnail.
+ *     description: The URL of the inventory item's thumbnail.
  *   metadata:
  *     type: object
- *     description: The inventory item's metadata.
+ *     description: The inventory item's metadata, can hold custom key-value pairs.
  *   location_levels:
  *     type: array
- *     description: The inventory item's location levels.
+ *     description: The inventory item's associated inventory levels.
  *     items:
  *       $ref: "#/components/schemas/AdminInventoryLevel"
  * 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminInventoryItemResponse
  * type: object
- * description: SUMMARY
+ * description: The inventory item's details.
  * x-schemaName: AdminInventoryItemResponse
  * required:
  *   - inventory_item

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminInventoryLevel
  * type: object
- * description: The location level's location levels.
+ * description: The inventory level's details.
  * x-schemaName: AdminInventoryLevel
  * required:
  *   - id
@@ -22,60 +22,51 @@
  *   id:
  *     type: string
  *     title: id
- *     description: The location level's ID.
+ *     description: The inventory level's ID.
- *   created_at:
- *     type: string
- *     format: date-time
- *     title: created_at
- *     description: The location level's created at.
- *   updated_at:
- *     type: string
- *     format: date-time
- *     title: updated_at
- *     description: The location level's updated at.
- *   deleted_at:
- *     type: string
- *     format: date-time
- *     title: deleted_at
- *     description: The location level's deleted at.
  *   inventory_item_id:
  *     type: string
  *     title: inventory_item_id
- *     description: The location level's inventory item id.
+ *     description: The ID of the inventory item this level belongs to.
  *   location_id:
  *     type: string
  *     title: location_id
- *     description: The location level's location id.
+ *     description: The ID of the stock location this level belongs to.
  *   stocked_quantity:
  *     type: number
  *     title: stocked_quantity
- *     description: The location level's stocked quantity.
+ *     description: The quantity of the associated inventory item stocked in the associated stock location.
- *   raw_stocked_quantity:
- *     type: object
- *     description: The location level's raw stocked quantity.
  *   reserved_quantity:
  *     type: number
  *     title: reserved_quantity
- *     description: The location level's reserved quantity.
+ *     description: The reserved quantity of the associated inventory item stocked in the associated stock location.
- *   raw_reserved_quantity:
- *     type: object
- *     description: The location level's raw reserved quantity.
  *   incoming_quantity:
  *     type: number
  *     title: incoming_quantity
- *     description: The location level's incoming quantity.
+ *     description: The incoming quantity of the associated inventory item stocked in the associated stock location.
- *   raw_incoming_quantity:
- *     type: object
- *     description: The location level's raw incoming quantity.
  *   metadata:
  *     type: object
- *     description: The location level's metadata.
+ *     description: The location level's metadata, can hold custom key-value pairs.
  *   inventory_item:
  *     $ref: "#/components/schemas/AdminInventoryItem"
  *   available_quantity:
  *     type: number
  *     title: available_quantity
- *     description: The location level's available quantity.
+ *     description: The quantity available for order of the associated inventory item in the associated stock location.
+ *   created_at:
+ *     type: string
+ *     format: date-time
+ *     title: created_at
+ *     description: The date the inventory level was created.
+ *   updated_at:
+ *     type: string
+ *     format: date-time
+ *     title: updated_at
+ *     description: The date the inventory level was updated.
+ *   deleted_at:
+ *     type: string
+ *     format: date-time
+ *     title: deleted_at
+ *     description: The date the inventory level was deleted.
  * 
 */
 

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

@@ -21,7 +21,7 @@
  *   accepted:
  *     type: boolean
  *     title: accepted
- *     description: The invite's accepted.
+ *     description: Whether the invite has been accepted.
  *   token:
  *     type: string
  *     title: token
@@ -29,21 +29,21 @@
  *   expires_at:
  *     type: string
  *     title: expires_at
- *     description: The invite's expires at.
+ *     description: The invite's expiry date.
  *     format: date-time
  *   metadata:
  *     type: object
- *     description: The invite's metadata.
+ *     description: The invite's metadata, can hold custom key-value pairs.
  *   created_at:
  *     type: string
  *     format: date-time
  *     title: created_at
- *     description: The invite's created at.
+ *     description: The date the invite was created.
  *   updated_at:
  *     type: string
  *     format: date-time
  *     title: updated_at
- *     description: The invite's updated at.
+ *     description: The date the invite was updated.
  * 
 */
 

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

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

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminLinkPriceListProducts
  * type: object
- * description: The removal details.
+ * description: The products removal details.
  * properties:
  *   remove:
  *     type: array

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

@@ -18,51 +18,54 @@
  *   to:
  *     type: string
  *     title: to
- *     description: The notification's to.
+ *     description: Where to send the notification to. For example, if `channel` is `email`, this can be an email number.
  *   channel:
  *     type: string
  *     title: channel
- *     description: The notification's channel.
+ *     description: Through which channel is the notification sent through.
+ *     example: email
  *   template:
  *     type: string
  *     title: template
- *     description: The notification's template.
+ *     description: The ID of the template in a third-party service used as the notification's shape.
  *   data:
  *     type: object
- *     description: The notification's data.
+ *     description: Data payload to send with the notification.
  *   trigger_type:
  *     type: string
  *     title: trigger_type
- *     description: The notification's trigger type.
+ *     description: What triggered this notification.
+ *     example: order.created
  *   resource_id:
  *     type: string
  *     title: resource_id
- *     description: The notification's resource id.
+ *     description: The ID of the associated resource. For example, if the notification was triggered because an order was created, this would be the ID of the order.
  *   resource_type:
  *     type: string
  *     title: resource_type
- *     description: The notification's resource type.
+ *     description: The type of the resource that triggered the notification.
+ *     example: order
  *   receiver_id:
  *     type: string
  *     title: receiver_id
- *     description: The notification's receiver id.
+ *     description: The ID of the user or customer that's receiving this notification.
  *   original_notification_id:
  *     type: string
  *     title: original_notification_id
- *     description: The notification's original notification id.
+ *     description: The ID of the original notification, if this notification is resent.
  *   external_id:
  *     type: string
  *     title: external_id
- *     description: The notification's external id.
+ *     description: The ID of the notification in an external or third-party system.
  *   provider_id:
  *     type: string
  *     title: provider_id
- *     description: The notification's provider id.
+ *     description: The ID of the provider used to send the notification.
  *   created_at:
  *     type: string
  *     format: date-time
  *     title: created_at
- *     description: The notification's created at.
+ *     description: The date the notification was created.
  * 
 */
 

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

@@ -55,7 +55,7 @@ type AuthRequests = {
 class OasKindGenerator extends FunctionKindGenerator {
   public name = "oas"
   protected allowedKinds: SyntaxKind[] = [ts.SyntaxKind.FunctionDeclaration]
-  private MAX_LEVEL = 4
+  private MAX_LEVEL = 5
   readonly REQUEST_TYPE_NAMES = [
     "MedusaRequest",
     "RequestWithContext",