oas: [10/n] improve admin oas (#8959)

www/utils/generated/oas-output/operations/admin/post_admin_fulfillments.ts

@@ -2,7 +2,7 @@
  * @oas [post] /admin/fulfillments
  * operationId: PostFulfillments
  * summary: Create Fulfillment
- * description: Create a fulfillment.
+ * description: Create a fulfillment for an order, return, exchange, and more.
  * x-authenticated: true
  * parameters:
  *   - name: expand

www/utils/generated/oas-output/operations/admin/post_admin_fulfillments_[id]_cancel.ts

@@ -1,8 +1,12 @@
 /**
  * @oas [post] /admin/fulfillments/{id}/cancel
  * operationId: PostFulfillmentsIdCancel
- * summary: Add Cancels to Fulfillment
+ * summary: Cancel a Fulfillment
- * description: Add a list of cancels to a fulfillment.
+ * description: >
+ *   Cancel a fulfillment. The fulfillment can't be shipped or delivered.
+ * 
+ *   
+ *   To cancel the fulfillment, the `cancelFulfillment` method of the associated fulfillment provider is used.
  * x-authenticated: true
  * parameters:
  *   - name: id

www/utils/generated/oas-output/operations/admin/post_admin_fulfillments_[id]_shipment.ts

@@ -1,8 +1,9 @@
 /**
  * @oas [post] /admin/fulfillments/{id}/shipment
  * operationId: PostFulfillmentsIdShipment
- * summary: Add Shipments to Fulfillment
+ * summary: Create a Shipment for a Fulfillment
- * description: Add a list of shipments to a fulfillment.
+ * x-sidebar-summary: Create Shipment
+ * description: Create a shipment for a fulfillment. The fulfillment must not be shipped or canceled.
  * x-authenticated: true
  * parameters:
  *   - name: id

www/utils/generated/oas-output/operations/admin/post_admin_inventory-items.ts

@@ -2,7 +2,7 @@
  * @oas [post] /admin/inventory-items
  * operationId: PostInventoryItems
  * summary: Create Inventory Item
- * description: Create a inventory item.
+ * description: Create an inventory item.
  * x-authenticated: true
  * parameters:
  *   - name: expand

www/utils/generated/oas-output/operations/admin/post_admin_inventory-items_[id].ts

@@ -1,8 +1,8 @@
 /**
  * @oas [post] /admin/inventory-items/{id}
  * operationId: PostInventoryItemsId
- * summary: Update a Inventory Item
+ * summary: Update an Inventory Item
- * description: Update a inventory item's details.
+ * description: Update an inventory item's details.
  * x-authenticated: true
  * parameters:
  *   - name: id
@@ -62,7 +62,7 @@
  *     application/json:
  *       schema:
  *         type: object
- *         description: SUMMARY
+ *         description: The properties to update in the inventory item.
  *         required:
  *           - sku
  *           - hs_code
@@ -81,11 +81,11 @@
  *           sku:
  *             type: string
  *             title: sku
- *             description: The inventory item's sku.
+ *             description: The inventory item's SKU.
  *           hs_code:
  *             type: string
  *             title: hs_code
- *             description: The inventory item's hs code.
+ *             description: The inventory item's HS code.
  *           weight:
  *             type: number
  *             title: weight
@@ -109,7 +109,7 @@
  *           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
@@ -125,14 +125,14 @@
  *           requires_shipping:
  *             type: boolean
  *             title: requires_shipping
- *             description: The inventory item's requires shipping.
+ *             description: Whether the inventory item requires shipping.
  *           thumbnail:
  *             type: string
  *             title: thumbnail
- *             description: The inventory item's thumbnail.
+ *             description: The URL of an image to be used as the inventory item's thumbnail. You can use the Upload API routes to upload an image and get its URL.
  *           metadata:
  *             type: object
- *             description: The inventory item's metadata.
+ *             description: The inventory item's metadata. Can be custom data in key-value pairs.
  * x-codeSamples:
  *   - lang: Shell
  *     label: cURL

www/utils/generated/oas-output/operations/admin/post_admin_inventory-items_[id]_location-levels.ts

@@ -1,8 +1,9 @@
 /**
  * @oas [post] /admin/inventory-items/{id}/location-levels
  * operationId: PostInventoryItemsIdLocationLevels
- * summary: Add Location Levels to Inventory Item
+ * summary: Create Inventory Level for Inventory Item
- * description: Add a list of location levels to a inventory item.
+ * x-sidebar-summary: Create Inventory Level
+ * description: Create an inventory level for an inventory item.
  * x-authenticated: true
  * parameters:
  *   - name: id
@@ -62,22 +63,22 @@
  *     application/json:
  *       schema:
  *         type: object
- *         description: SUMMARY
+ *         description: The inventory level's details.
  *         required:
  *           - location_id
  *         properties:
  *           location_id:
  *             type: string
  *             title: location_id
- *             description: The inventory item's location id.
+ *             description: The ID of the associated location.
  *           stocked_quantity:
  *             type: number
  *             title: stocked_quantity
- *             description: The inventory item's stocked quantity.
+ *             description: The inventory level's stocked quantity.
  *           incoming_quantity:
  *             type: number
  *             title: incoming_quantity
- *             description: The inventory item's incoming quantity.
+ *             description: The inventory level's incoming quantity.
  * x-codeSamples:
  *   - lang: Shell
  *     label: cURL

www/utils/generated/oas-output/operations/admin/post_admin_inventory-items_[id]_location-levels_[location_id].ts

@@ -1,8 +1,9 @@
 /**
  * @oas [post] /admin/inventory-items/{id}/location-levels/{location_id}
  * operationId: PostInventoryItemsIdLocationLevelsLocation_id
- * summary: Add Location Levels to Inventory Item
+ * summary: Update an Inventory Level of an Inventory Item
- * description: Add a list of location levels to a inventory item.
+ * x-sidebar-summary: Update Inventory Level
+ * description: Updates the details of an inventory item's inventory level using its associated location ID.
  * x-authenticated: true
  * parameters:
  *   - name: id
@@ -13,7 +14,7 @@
  *       type: string
  *   - name: location_id
  *     in: path
- *     description: The inventory item's location id.
+ *     description: The ID of the location associated with the inventory level.
  *     required: true
  *     schema:
  *       type: string
@@ -68,16 +69,16 @@
  *     application/json:
  *       schema:
  *         type: object
- *         description: SUMMARY
+ *         description: The properties to update in the inventory level.
  *         properties:
  *           stocked_quantity:
  *             type: number
  *             title: stocked_quantity
- *             description: The inventory item's stocked quantity.
+ *             description: The inventory level's stocked quantity.
  *           incoming_quantity:
  *             type: number
  *             title: incoming_quantity
- *             description: The inventory item's incoming quantity.
+ *             description: The inventory level's incoming quantity.
  * x-codeSamples:
  *   - lang: Shell
  *     label: cURL

www/utils/generated/oas-output/operations/admin/post_admin_inventory-items_[id]_location-levels_batch.ts

@@ -1,8 +1,9 @@
 /**
  * @oas [post] /admin/inventory-items/{id}/location-levels/batch
  * operationId: PostInventoryItemsIdLocationLevelsBatch
- * summary: Add Location Levels to Inventory Item
+ * summary: Manage Inventory Levels of Inventory Item
- * description: Add a list of location levels to a inventory item.
+ * x-sidebar-summary: Manage Inventory Levels
+ * description: Manage the inventory levels of an inventory item to create or delete them.
  * x-authenticated: true
  * parameters:
  *   - name: id
@@ -20,51 +21,51 @@
  *     application/json:
  *       schema:
  *         type: object
- *         description: SUMMARY
+ *         description: The inventory levels to create or delete.
  *         properties:
  *           create:
  *             type: array
- *             description: The inventory item's create.
+ *             description: The inventory levels to create.
  *             items:
  *               type: object
- *               description: The create's details.
+ *               description: The inventory level's details.
  *               required:
  *                 - location_id
  *               properties:
  *                 location_id:
  *                   type: string
  *                   title: location_id
- *                   description: The create's location id.
+ *                   description: The ID of the associated location.
  *                 stocked_quantity:
  *                   type: number
  *                   title: stocked_quantity
- *                   description: The create's stocked quantity.
+ *                   description: The inventory level's stocked quantity.
  *                 incoming_quantity:
  *                   type: number
  *                   title: incoming_quantity
- *                   description: The create's incoming quantity.
+ *                   description: The inventory level's incoming quantity.
  *           update:
  *             type: array
- *             description: The inventory item's update.
+ *             description: The inventory levels to update.
  *             items:
  *               type: object
- *               description: The update's details.
+ *               description: The inventory level's details.
  *               properties:
  *                 stocked_quantity:
  *                   type: number
  *                   title: stocked_quantity
- *                   description: The update's stocked quantity.
+ *                   description: The inventory level's stocked quantity.
  *                 incoming_quantity:
  *                   type: number
  *                   title: incoming_quantity
- *                   description: The update's incoming quantity.
+ *                   description: The inventory level's incoming quantity.
  *           delete:
  *             type: array
- *             description: The inventory item's delete.
+ *             description: The inventory levels to delete.
  *             items:
  *               type: string
  *               title: delete
- *               description: The delete's details.
+ *               description: The ID of the inventory level to delete.
  * x-codeSamples:
  *   - lang: Shell
  *     label: cURL
@@ -80,7 +81,7 @@
  *       application/json:
  *         schema:
  *           type: object
- *           description: SUMMARY
+ *           description: The inventory item's details.
  *           required:
  *             - inventory_item
  *           properties:

www/utils/generated/oas-output/operations/admin/post_admin_invites.ts

@@ -52,18 +52,18 @@
  *     application/json:
  *       schema:
  *         type: object
- *         description: SUMMARY
+ *         description: The invite's details.
  *         required:
  *           - email
  *         properties:
  *           email:
  *             type: string
  *             title: email
- *             description: The invite's email.
+ *             description: The email of the user to invite.
  *             format: email
  *           metadata:
  *             type: object
- *             description: The invite's metadata.
+ *             description: The invite's metadata. Can be custom data in key-value pairs.
  * x-codeSamples:
  *   - lang: Shell
  *     label: cURL

www/utils/generated/oas-output/operations/admin/post_admin_invites_[id]_resend.ts

@@ -1,8 +1,8 @@
 /**
  * @oas [post] /admin/invites/{id}/resend
  * operationId: PostInvitesIdResend
- * summary: Add Resends to Invite
+ * summary: Refresh Invite Token
- * description: Add a list of resends to a invite.
+ * description: Refresh the token of an invite.
  * x-authenticated: false
  * parameters:
  *   - name: id

www/utils/generated/oas-output/operations/admin/post_admin_invites_accept.ts

@@ -1,8 +1,12 @@
 /**
  * @oas [post] /admin/invites/accept
  * operationId: PostInvitesAccept
- * summary: Create Invite
+ * summary: Accept Invite
- * description: Create a invite.
+ * description: >
+ *   Accept an invite and create a new user.
+ * 
+ *   Since the user isn't created yet, the JWT token used in the authorization header is retrieved from the `/auth/user/emailpass/register` API route (or a provider other than `emailpass`).
+ *   The user can then authenticate using the `/auth/user/emailpass` API route.
  * x-authenticated: false
  * parameters:
  *   - name: expand
@@ -52,7 +56,7 @@
  *     application/json:
  *       schema:
  *         type: object
- *         description: SUMMARY
+ *         description: The details of the user to be created.
  *         required:
  *           - email
  *           - first_name
@@ -61,16 +65,16 @@
  *           email:
  *             type: string
  *             title: email
- *             description: The invite's email.
+ *             description: The user's email.
  *             format: email
  *           first_name:
  *             type: string
  *             title: first_name
- *             description: The invite's first name.
+ *             description: The user's first name.
  *           last_name:
  *             type: string
  *             title: last_name
- *             description: The invite's last name.
+ *             description: The user's last name.
  * x-codeSamples:
  *   - lang: Shell
  *     label: cURL
@@ -92,21 +96,21 @@
  *         schema:
  *           oneOf:
  *             - type: object
- *               description: SUMMARY
+ *               description: The created user's details.
  *               required:
  *                 - user
  *               properties:
  *                 user:
  *                   $ref: "#/components/schemas/AdminUser"
  *             - type: object
- *               description: SUMMARY
+ *               description: An error's details.
  *               required:
  *                 - message
  *               properties:
  *                 message:
  *                   type: string
  *                   title: message
- *                   description: The invite's message.
+ *                   description: The error message.
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

www/utils/generated/oas-output/operations/admin/post_admin_order-edits.ts

@@ -2,7 +2,7 @@
  * @oas [post] /admin/order-edits
  * operationId: PostOrderEdits
  * summary: Create Order Edit
- * description: Create a order edit.
+ * description: Create an order edit.
  * x-authenticated: true
  * parameters: []
  * security:

www/utils/generated/oas-output/operations/admin/post_admin_order-edits_[id]_confirm.ts

@@ -1,8 +1,8 @@
 /**
  * @oas [post] /admin/order-edits/{id}/confirm
  * operationId: PostOrderEditsIdConfirm
- * summary: Add Confirms to Order Edit
+ * summary: Confirm Order Edit
- * description: Add a list of confirms to a order edit.
+ * description: Confirm an order edit request and apply the changes on the order.
  * x-authenticated: true
  * parameters:
  *   - name: id
@@ -43,10 +43,6 @@
  *   "500":
  *     $ref: "#/components/responses/500_error"
  * x-workflow: confirmOrderEditRequestWorkflow
- * requestBody:
- *   content:
- *     application/json:
- *       schema: {}
  * 
 */
 

www/utils/generated/oas-output/operations/admin/post_admin_order-edits_[id]_items.ts

@@ -2,7 +2,8 @@
  * @oas [post] /admin/order-edits/{id}/items
  * operationId: PostOrderEditsIdItems
  * summary: Add Items to Order Edit
- * description: Add a list of items to a order edit.
+ * x-sidebar-summary: Add Items
+ * description: Add new items to an order edit. These items will have the action `ITEM_ADD`.
  * x-authenticated: true
  * parameters:
  *   - name: id

www/utils/generated/oas-output/operations/admin/post_admin_order-edits_[id]_items_[action_id].ts

@@ -1,8 +1,12 @@
 /**
  * @oas [post] /admin/order-edits/{id}/items/{action_id}
  * operationId: PostOrderEditsIdItemsAction_id
- * summary: Add Items to Order Edit
+ * summary: Update an Item in an Order Edit
- * description: Add a list of items to a order edit.
+ * x-sidebar-summary: Update Item
+ * description: |
+ *   Update an added item in the order edit by the ID of the item's `ITEM_ADD` action.
+ * 
+ *   Every item has an `actions` property, whose value is an array of actions. You can check the action's name using its `action` property, and use the value of the `id` property.
  * x-authenticated: true
  * parameters:
  *   - name: id
@@ -13,7 +17,7 @@
  *       type: string
  *   - name: action_id
  *     in: path
- *     description: The order edit's action id.
+ *     description: The ID of the new item's `ITEM_ADD` action.
  *     required: true
  *     schema:
  *       type: string

www/utils/generated/oas-output/operations/admin/post_admin_order-edits_[id]_items_item_[item_id].ts

@@ -1,8 +1,9 @@
 /**
  * @oas [post] /admin/order-edits/{id}/items/item/{item_id}
  * operationId: PostOrderEditsIdItemsItemItem_id
- * summary: Add Items to Order Edit
+ * summary: Update Order Item Quantity of Order Edit
- * description: Add a list of items to a order edit.
+ * x-sidebar-summary: Update Item Quantity
+ * description: Update an existing order item's quantity of an order edit.
  * x-authenticated: true
  * parameters:
  *   - name: id

www/utils/generated/oas-output/operations/admin/post_admin_order-edits_[id]_request.ts

@@ -1,8 +1,8 @@
 /**
  * @oas [post] /admin/order-edits/{id}/request
  * operationId: PostOrderEditsIdRequest
- * summary: Add Requests to Order Edit
+ * summary: Request Order Edit
- * description: Add a list of requests to a order edit.
+ * description: Change the status of an active order edit to requested.
  * x-authenticated: true
  * parameters:
  *   - name: id
@@ -43,10 +43,6 @@
  *   "500":
  *     $ref: "#/components/responses/500_error"
  * x-workflow: requestOrderEditRequestWorkflow
- * requestBody:
- *   content:
- *     application/json:
- *       schema: {}
  * 
 */
 

www/utils/generated/oas-output/operations/admin/post_admin_order-edits_[id]_shipping-method.ts

@@ -1,8 +1,9 @@
 /**
  * @oas [post] /admin/order-edits/{id}/shipping-method
  * operationId: PostOrderEditsIdShippingMethod
- * summary: Add Shipping Methods to Order Edit
+ * summary: Add Shipping Method to Order Edit
- * description: Add a list of shipping methods to a order edit.
+ * x-sidebar-summary: Add Shipping Method
+ * description: Add a shipping method to an exchange. The shipping method will have a `SHIPPING_ADD` action.
  * x-authenticated: true
  * parameters:
  *   - name: id

www/utils/generated/oas-output/operations/admin/post_admin_order-edits_[id]_shipping-method_[action_id].ts

@@ -1,8 +1,12 @@
 /**
  * @oas [post] /admin/order-edits/{id}/shipping-method/{action_id}
  * operationId: PostOrderEditsIdShippingMethodAction_id
- * summary: Add Shipping Methods to Order Edit
+ * summary: Update Shipping Method of an Order Edit
- * description: Add a list of shipping methods to a order edit.
+ * x-sidebar-summary: Update Shipping Method
+ * description: |
+ *   Update a shipping method in the order edit by the ID of the method's `SHIPPING_ADD` action.
+ * 
+ *   Every shipping method has an `actions` property, whose value is an array of actions. You can check the action's name using its `action` property, and use the value of the `id` property.
  * x-authenticated: true
  * parameters:
  *   - name: id
@@ -13,7 +17,7 @@
  *       type: string
  *   - name: action_id
  *     in: path
- *     description: The order edit's action id.
+ *     description: The ID of the shipping method's `SHIPPING_ADD` action.
  *     required: true
  *     schema:
  *       type: string

www/utils/generated/oas-output/operations/admin/post_admin_orders_[id]_archive.ts

@@ -1,8 +1,8 @@
 /**
  * @oas [post] /admin/orders/{id}/archive
  * operationId: PostOrdersIdArchive
- * summary: Add Archives to Order
+ * summary: Archive an Order
- * description: Add a list of archives to a order.
+ * description: Change the status of an order to archived.
  * x-authenticated: true
  * parameters:
  *   - name: id