chore(oas): [8/n] improve oas schemas (#9163)

Improve OAS schemas [8/n]

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

@@ -1,20 +1,20 @@
 /**
  * @schema AdminPostExchangesShippingActionReqSchema
  * type: object
- * description: SUMMARY
+ * description: The details of the shipping method to update.
  * x-schemaName: AdminPostExchangesShippingActionReqSchema
  * properties:
  *   custom_amount:
  *     type: number
  *     title: custom_amount
- *     description: The exchange's custom amount.
+ *     description: The shipping method's custom amount.
  *   internal_note:
  *     type: string
  *     title: internal_note
- *     description: The exchange's internal note.
+ *     description: A note viewed by admin users only.
  *   metadata:
  *     type: object
- *     description: The exchange's metadata.
+ *     description: The exchange's metadata, can hold custom key-value pairs.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminPostExchangesShippingReqSchema
  * type: object
- * description: SUMMARY
+ * description: The outbound shipping method's details.
  * x-schemaName: AdminPostExchangesShippingReqSchema
  * required:
  *   - shipping_option_id
@@ -9,22 +9,22 @@
  *   shipping_option_id:
  *     type: string
  *     title: shipping_option_id
- *     description: The exchange's shipping option id.
+ *     description: The ID of the associated shipping option.
  *   custom_amount:
  *     type: number
  *     title: custom_amount
- *     description: The exchange's custom amount.
+ *     description: Set a custom amount for the shipping method.
  *   description:
  *     type: string
  *     title: description
- *     description: The exchange's description.
+ *     description: The shipping method's description.
  *   internal_note:
  *     type: string
  *     title: internal_note
- *     description: The exchange's internal note.
+ *     description: A note viewed by admin users only.
  *   metadata:
  *     type: object
- *     description: The exchange's metadata.
+ *     description: The exchange's metadata, can hold custom key-value pairs.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminPostOrderClaimsReqSchema
  * type: object
- * description: SUMMARY
+ * description: The claim's details.
  * x-schemaName: AdminPostOrderClaimsReqSchema
  * required:
  *   - type
@@ -16,7 +16,7 @@
  *   order_id:
  *     type: string
  *     title: order_id
- *     description: The claim's order id.
+ *     description: The ID of the order the claim is created for.
  *   description:
  *     type: string
  *     title: description
@@ -24,14 +24,14 @@
  *   internal_note:
  *     type: string
  *     title: internal_note
- *     description: The claim's internal note.
+ *     description: A note viewed only by admin users.
  *   reason_id:
  *     type: string
  *     title: reason_id
- *     description: The claim's reason id.
+ *     description: The ID of the associated return reason.
  *   metadata:
  *     type: object
- *     description: The claim's metadata.
+ *     description: The claim's metadata, can hold custom key-value pairs.
  * 
 */
 

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

@@ -1,15 +1,15 @@
 /**
  * @schema AdminPostOrderEditsAddItemsReqSchema
  * type: object
- * description: SUMMARY
+ * description: The details of items to be edited.
  * x-schemaName: AdminPostOrderEditsAddItemsReqSchema
  * properties:
  *   items:
  *     type: array
- *     description: The order edit's items.
+ *     description: The details of items to be edited.
  *     items:
  *       type: object
- *       description: The item's items.
+ *       description: An item's details.
  *       required:
  *         - variant_id
  *         - quantity
@@ -17,7 +17,7 @@
  *         variant_id:
  *           type: string
  *           title: variant_id
- *           description: The item's variant id.
+ *           description: The ID of the associated product variant.
  *         quantity:
  *           type: number
  *           title: quantity
@@ -29,14 +29,14 @@
  *         internal_note:
  *           type: string
  *           title: internal_note
- *           description: The item's internal note.
+ *           description: A note viewed only by admin users.
  *         allow_backorder:
  *           type: boolean
  *           title: allow_backorder
- *           description: The item's allow backorder.
+ *           description: Whether the item can be added even if there's no available invenotory quantity of the variant.
  *         metadata:
  *           type: object
- *           description: The item's metadata.
+ *           description: The item's metadata, can hold custom key-value pairs.
  * 
 */
 

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

@@ -1,17 +1,17 @@
 /**
  * @schema AdminPostOrderEditsItemsActionReqSchema
  * type: object
- * description: SUMMARY
+ * description: The details to update in the item.
  * x-schemaName: AdminPostOrderEditsItemsActionReqSchema
  * properties:
  *   quantity:
  *     type: number
  *     title: quantity
- *     description: The order edit's quantity.
+ *     description: The item's quantity.
  *   internal_note:
  *     type: string
  *     title: internal_note
- *     description: The order edit's internal note.
+ *     description: A note viewed only by admin users.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminPostOrderEditsReqSchema
  * type: object
- * description: SUMMARY
+ * description: The order edit's details.
  * x-schemaName: AdminPostOrderEditsReqSchema
  * required:
  *   - order_id
@@ -9,7 +9,7 @@
  *   order_id:
  *     type: string
  *     title: order_id
- *     description: The order edit's order id.
+ *     description: The ID of the order this edit is for.
  *   description:
  *     type: string
  *     title: description
@@ -17,10 +17,10 @@
  *   internal_note:
  *     type: string
  *     title: internal_note
- *     description: The order edit's internal note.
+ *     description: A note viewed only by admin users.
  *   metadata:
  *     type: object
- *     description: The order edit's metadata.
+ *     description: The order edit's metadata, can hold custom key-value pairs.
  * 
 */
 

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

@@ -1,20 +1,20 @@
 /**
  * @schema AdminPostOrderEditsShippingActionReqSchema
  * type: object
- * description: SUMMARY
+ * description: The shipping method's details.
  * x-schemaName: AdminPostOrderEditsShippingActionReqSchema
  * properties:
  *   custom_amount:
  *     type: number
  *     title: custom_amount
- *     description: The order edit's custom amount.
+ *     description: Set a custom price for the shipping method.
  *   internal_note:
  *     type: string
  *     title: internal_note
- *     description: The order edit's internal note.
+ *     description: A note viewed only by admin users.
  *   metadata:
  *     type: object
- *     description: The order edit's metadata.
+ *     description: The order edit's metadata, can hold custom key-value pairs.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminPostOrderEditsShippingReqSchema
  * type: object
- * description: SUMMARY
+ * description: The shipping method's details.
  * x-schemaName: AdminPostOrderEditsShippingReqSchema
  * required:
  *   - shipping_option_id
@@ -9,22 +9,22 @@
  *   shipping_option_id:
  *     type: string
  *     title: shipping_option_id
- *     description: The order edit's shipping option id.
+ *     description: The ID of the associated shipping option.
  *   custom_amount:
  *     type: number
  *     title: custom_amount
- *     description: The order edit's custom amount.
+ *     description: Set a custom price for the shipping method.
  *   description:
  *     type: string
  *     title: description
- *     description: The order edit's description.
+ *     description: The shipping method's description.
  *   internal_note:
  *     type: string
  *     title: internal_note
- *     description: The order edit's internal note.
+ *     description: A note viewed only by admin users.
  *   metadata:
  *     type: object
- *     description: The order edit's metadata.
+ *     description: The shipping method's metadata, can hold custom key-value pairs.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminPostOrderEditsUpdateItemQuantityReqSchema
  * type: object
- * description: SUMMARY
+ * description: The order item's details to update.
  * x-schemaName: AdminPostOrderEditsUpdateItemQuantityReqSchema
  * required:
  *   - quantity
@@ -9,11 +9,11 @@
  *   quantity:
  *     type: number
  *     title: quantity
- *     description: The order edit's quantity.
+ *     description: The item's quantity.
  *   internal_note:
  *     type: string
  *     title: internal_note
- *     description: The order edit's internal note.
+ *     description: A note viewed only by admin users.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminPostOrderExchangesReqSchema
  * type: object
- * description: SUMMARY
+ * description: The exchange's details.
  * x-schemaName: AdminPostOrderExchangesReqSchema
  * required:
  *   - order_id
@@ -9,7 +9,7 @@
  *   order_id:
  *     type: string
  *     title: order_id
- *     description: The exchange's order id.
+ *     description: The ID of the order this exchange is created for.
  *   description:
  *     type: string
  *     title: description
@@ -17,10 +17,10 @@
  *   internal_note:
  *     type: string
  *     title: internal_note
- *     description: The exchange's internal note.
+ *     description: A note viewed only by admin users.
  *   metadata:
  *     type: object
- *     description: The exchange's metadata.
+ *     description: The exchange's metadata, can hold custom key-value pairs.
  * 
 */
 

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

@@ -1,20 +1,20 @@
 /**
  * @schema AdminPostReceiveReturnsReqSchema
  * type: object
- * description: SUMMARY
+ * description: The return receival details.
  * x-schemaName: AdminPostReceiveReturnsReqSchema
  * properties:
  *   internal_note:
  *     type: string
  *     title: internal_note
- *     description: The return's internal note.
+ *     description: A note viewed only by admin users.
  *   description:
  *     type: string
  *     title: description
  *     description: The return's description.
  *   metadata:
  *     type: object
- *     description: The return's metadata.
+ *     description: The return's metadata, can hold custom key-value pairs.
  * 
 */
 

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

@@ -1,13 +1,13 @@
 /**
  * @schema AdminPostReturnsConfirmRequestReqSchema
  * type: object
- * description: SUMMARY
+ * description: The confirmation's details.
  * x-schemaName: AdminPostReturnsConfirmRequestReqSchema
  * properties:
  *   no_notification:
  *     type: boolean
  *     title: no_notification
- *     description: The return's no notification.
+ *     description: Whether to send the customer a notification about the confirmation.
  * 
 */
 

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

@@ -1,17 +1,17 @@
 /**
  * @schema AdminPostReturnsDismissItemsActionReqSchema
  * type: object
- * description: SUMMARY
+ * description: The details to update of the damaged item.
  * x-schemaName: AdminPostReturnsDismissItemsActionReqSchema
  * properties:
  *   quantity:
  *     type: number
  *     title: quantity
- *     description: The return's quantity.
+ *     description: The item's quantity.
  *   internal_note:
  *     type: string
  *     title: internal_note
- *     description: The return's internal note.
+ *     description: A note viewed only by admin users.
  * 
 */
 

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

@@ -1,17 +1,17 @@
 /**
  * @schema AdminPostReturnsReceiveItemsActionReqSchema
  * type: object
- * description: SUMMARY
+ * description: The details of the received item.
  * x-schemaName: AdminPostReturnsReceiveItemsActionReqSchema
  * properties:
  *   quantity:
  *     type: number
  *     title: quantity
- *     description: The return's quantity.
+ *     description: The item's quantity.
  *   internal_note:
  *     type: string
  *     title: internal_note
- *     description: The return's internal note.
+ *     description: A note viewed only by admin users.
  * 
 */
 

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

@@ -1,15 +1,15 @@
 /**
  * @schema AdminPostReturnsReceiveItemsReqSchema
  * type: object
- * description: SUMMARY
+ * description: The items details.
  * x-schemaName: AdminPostReturnsReceiveItemsReqSchema
  * properties:
  *   items:
  *     type: array
- *     description: The return's items.
+ *     description: The items details.
  *     items:
  *       type: object
- *       description: The item's items.
+ *       description: An item's details.
  *       required:
  *         - id
  *         - quantity
@@ -17,7 +17,7 @@
  *         id:
  *           type: string
  *           title: id
- *           description: The item's ID.
+ *           description: The ID of the item in the order.
  *         quantity:
  *           type: number
  *           title: quantity
@@ -29,7 +29,7 @@
  *         internal_note:
  *           type: string
  *           title: internal_note
- *           description: The item's internal note.
+ *           description: A note viewed only by admin users.
  * 
 */
 

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

@@ -1,7 +1,7 @@
 /**
  * @schema AdminPostReturnsReqSchema
  * type: object
- * description: SUMMARY
+ * description: The return's details.
  * x-schemaName: AdminPostReturnsReqSchema
  * required:
  *   - order_id
@@ -9,11 +9,11 @@
  *   order_id:
  *     type: string
  *     title: order_id
- *     description: The return's order id.
+ *     description: The ID of the order the return belongs to.
  *   location_id:
  *     type: string
  *     title: location_id
- *     description: The return's location id.
+ *     description: The ID of the location the items are returned to.
  *   description:
  *     type: string
  *     title: description
@@ -21,14 +21,14 @@
  *   internal_note:
  *     type: string
  *     title: internal_note
- *     description: The return's internal note.
+ *     description: A note viewed only by admin users.
  *   no_notification:
  *     type: boolean
  *     title: no_notification
- *     description: The return's no notification.
+ *     description: Whether to send the customer a notification about the created return.
  *   metadata:
  *     type: object
- *     description: The return's metadata.
+ *     description: The return's metadata, can hold custom key-value pairs.
  * 
 */
 

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

@@ -1,24 +1,24 @@
 /**
  * @schema AdminPostReturnsRequestItemsActionReqSchema
  * type: object
- * description: SUMMARY
+ * description: The details to update in the item.
  * x-schemaName: AdminPostReturnsRequestItemsActionReqSchema
  * properties:
  *   quantity:
  *     type: number
  *     title: quantity
- *     description: The claim's quantity.
+ *     description: The item's quantity.
  *   internal_note:
  *     type: string
  *     title: internal_note
- *     description: The claim's internal note.
+ *     description: A note viewed only by admin users.
  *   reason_id:
  *     type: string
  *     title: reason_id
- *     description: The claim's reason id.
+ *     description: The ID of the associated return reason.
  *   metadata:
  *     type: object
- *     description: The claim's metadata.
+ *     description: The claim's metadata, can hold custom key-value pairs.
  * 
 */
 

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

@@ -1,15 +1,15 @@
 /**
  * @schema AdminPostReturnsRequestItemsReqSchema
  * type: object
- * description: SUMMARY
+ * description: The items' details.
  * x-schemaName: AdminPostReturnsRequestItemsReqSchema
  * properties:
  *   items:
  *     type: array
- *     description: The claim's items.
+ *     description: The items' details.
  *     items:
  *       type: object
- *       description: The item's items.
+ *       description: An item's details.
  *       required:
  *         - id
  *         - quantity
@@ -29,14 +29,14 @@
  *         internal_note:
  *           type: string
  *           title: internal_note
- *           description: The item's internal note.
+ *           description: A note viewed only by admin users.
  *         reason_id:
  *           type: string
  *           title: reason_id
- *           description: The item's reason id.
+ *           description: The ID of the associated return reason.
  *         metadata:
  *           type: object
- *           description: The item's metadata.
+ *           description: The item's metadata, can hold custom key-value pairs.
  * 
 */
 

www/utils/packages/docs-generator/src/classes/helpers/schema-factory.ts

@@ -31,6 +31,12 @@ class SchemaFactory {
     BigNumber: {
       type: "string",
     },
+    IBigNumber: {
+      type: "number",
+    },
+    BigNumberValue: {
+      type: "number",
+    },
   }
   /**
    * Schemas used only for response types.
@@ -60,7 +66,7 @@ class SchemaFactory {
   public tryGetSchema(
     name: string,
     additionalData?: Partial<OpenApiSchema>,
-    type: "request" | "response" | "all" = "all"
+    type: "request" | "query" | "response" | "all" = "all"
   ): OpenApiSchema | undefined {
     const schemasFactory =
       type === "response"

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

@@ -1047,7 +1047,7 @@ class OasKindGenerator extends FunctionKindGenerator {
                 itemType: propertyType,
                 title: propertyName,
                 descriptionOptions,
-                context: "request",
+                context: "query",
                 saveSchema: !forUpdate,
               }),
             })
@@ -1063,6 +1063,7 @@ class OasKindGenerator extends FunctionKindGenerator {
           typeReferenceNode: node.parameters[0].type,
           itemType: requestTypeArguments[0],
         })
+        const isQuery = methodName === "get"
         const parameterSchema = this.typeToSchema({
           itemType: requestTypeArguments[0],
           descriptionOptions: {
@@ -1070,13 +1071,13 @@ class OasKindGenerator extends FunctionKindGenerator {
             rawParentName: this.checker.typeToString(requestTypeArguments[0]),
           },
           zodObjectTypeName: zodObjectTypeName,
-          context: "request",
+          context: isQuery ? "query" : "request",
           saveSchema: !forUpdate,
         })
 
         // If function is a GET function, add the type parameter to the
         // query parameters instead of request parameters.
-        if (methodName === "get") {
+        if (isQuery) {
           if (parameterSchema.type === "object" && parameterSchema.properties) {
             Object.entries(parameterSchema.properties).forEach(
               ([key, propertySchema]) => {
@@ -1244,7 +1245,7 @@ class OasKindGenerator extends FunctionKindGenerator {
     /**
      * Whether the type is in a request / response
      */
-    context?: "request" | "response"
+    context?: "request" | "response" | "query"
     /**
      * Whether to save object schemas. Useful when only getting schemas to update.
      */
@@ -1550,6 +1551,7 @@ class OasKindGenerator extends FunctionKindGenerator {
             // if property's type is same as parent's property,
             // create a reference to the parent
             const arrHasParentType =
+              rest.context !== "query" &&
               this.checker.isArrayType(propertyType) &&
               this.areTypesEqual(
                 itemType,
@@ -1557,7 +1559,9 @@ class OasKindGenerator extends FunctionKindGenerator {
                   propertyType as ts.TypeReference
                 )[0]
               )
-            const isParentType = this.areTypesEqual(itemType, propertyType)
+            const isParentType =
+              rest.context !== "query" &&
+              this.areTypesEqual(itemType, propertyType)
 
             if (isParentType && objSchema["x-schemaName"]) {
               properties[property.name] = {