oas: [2/n] Improve admin OAS (#8866)

2024-08-29 20:07:17 +03:00
1 parent fbd93ab67c
commit 75c5853163
@@ -1,8 +1,8 @@
 /**
 * @oas [delete] /admin/order-edits/{id}
 * operationId: DeleteOrderEditsId
- * summary: Delete a Order Edit
+ * summary: Cancel Order Edit
- * description: Delete a order edit.
+ * description: Cancel an order edit.
 * x-authenticated: true
 * parameters:
 *   - name: id
@@ -93,14 +93,12 @@
 *             object:
 *               type: string
 *               title: object
- *               description: The order edit's object.
+ *               description: The name of the deleted object.
 *               default: "order-edit"
 *             deleted:
 *               type: boolean
 *               title: deleted
- *               description: The order edit's deleted.
+ *               description: Whether the order edit was deleted.
 *             parent:
 *               type: object
 *               description: The order edit's parent.
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
@@ -1,9 +1,14 @@
 /**
 * @oas [delete] /admin/order-edits/{id}/items/{action_id}
 * operationId: DeleteOrderEditsIdItemsAction_id
- * summary: Remove Items from Order Edit
+ * summary: Remove Item from Order Edit
- * description: Remove a list of items from a order edit. This doesn't delete the
+ * x-sidebar-summary: Remove Item
- *   Item, only the association between the Item and the order edit.
+ * description: >
 *   Remove 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
@@ -14,7 +19,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
@@ -1,10 +1,14 @@
 /**
 * @oas [delete] /admin/order-edits/{id}/shipping-method/{action_id}
 * operationId: DeleteOrderEditsIdShippingMethodAction_id
- * summary: Remove Shipping Methods from Order Edit
+ * summary: Remove Shipping Method from Order Edit
- * description: Remove a list of shipping methods from a order edit. This doesn't
+ * x-sidebar-summary: Remove Shipping Method
- *   delete the Shipping Method, only the association between the Shipping Method
+ * description: >
- *   and the order edit.
+ *   Remove 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
@@ -15,7 +19,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
@@ -93,14 +93,12 @@
 *             object:
 *               type: string
 *               title: object
- *               description: The payment collection's object.
+ *               description: The name of the deleted object.
 *               default: "payment-collection"
 *             deleted:
 *               type: boolean
 *               title: deleted
- *               description: The payment collection's deleted.
+ *               description: Whether the payment collection was deleted.
 *             parent:
 *               type: object
 *               description: The payment collection's parent.
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
@@ -2,7 +2,7 @@
 * @oas [delete] /admin/product-categories/{id}
 * operationId: DeleteProductCategoriesId
 * summary: Delete a Product Category
- * description: Delete a product category.
+ * description: Delete a product category. This doesn't deleted products in that category.
 * x-authenticated: true
 * parameters:
 *   - name: id
@@ -2,7 +2,7 @@
 * @oas [delete] /admin/product-tags/{id}
 * operationId: DeleteProductTagsId
 * summary: Delete a Product Tag
- * description: Delete a product tag.
+ * description: Delete a product tag. This doesn't delete products using the tag.
 * x-authenticated: true
 * parameters:
 *   - name: id
@@ -2,7 +2,7 @@
 * @oas [delete] /admin/product-types/{id}
 * operationId: DeleteProductTypesId
 * summary: Delete a Product Type
- * description: Delete a product type.
+ * description: Delete a product type. This doesn't delete products of this type.
 * x-authenticated: true
 * parameters:
 *   - name: id
@@ -1,9 +1,13 @@
 /**
 * @oas [delete] /admin/products/{id}/options/{option_id}
 * operationId: DeleteProductsIdOptionsOption_id
- * summary: Remove Options from Product
+ * summary: Delete an Option from Product
- * description: Remove a list of options from a product. This doesn't delete the
+ * x-sidebar-summary: Delete Option
- *   Option, only the association between the Option and the product.
+ * description: >
 *   Delete an option from a product.
 * 
 * 
 *   Values of this option in the product's variants are removed.
 * x-authenticated: true
 * parameters:
 *   - name: id
@@ -14,7 +18,7 @@
 *       type: string
 *   - name: option_id
 *     in: path
- *     description: The product's option id.
+ *     description: The product option's ID.
 *     required: true
 *     schema:
 *       type: string
@@ -1,9 +1,9 @@
 /**
 * @oas [delete] /admin/products/{id}/variants/{variant_id}
 * operationId: DeleteProductsIdVariantsVariant_id
- * summary: Remove Variants from Product
+ * summary: Delete Product Variant
- * description: Remove a list of variants from a product. This doesn't delete the
+ * x-sidebar-summary: Delete Variant
- *   Variant, only the association between the Variant and the product.
+ * description: Delete a variant of a product.
 * x-authenticated: true
 * parameters:
 *   - name: id
@@ -14,7 +14,7 @@
 *       type: string
 *   - name: variant_id
 *     in: path
- *     description: The product's variant id.
+ *     description: The product variant's ID.
 *     required: true
 *     schema:
 *       type: string
@@ -1,10 +1,9 @@
 /**
 * @oas [delete] /admin/products/{id}/variants/{variant_id}/inventory-items/{inventory_item_id}
 * operationId: DeleteProductsIdVariantsVariant_idInventoryItemsInventory_item_id
- * summary: Remove Inventory Items from Product
+ * summary: Remove Inventory Item Association with Product Variant
- * description: Remove a list of inventory items from a product. This doesn't
+ * x-sidebar-summary: Remove Inventory Item
- *   delete the Inventory Item, only the association between the Inventory Item and
+ * description: Remove the association between an inventory item and its product variant.
 *   the product.
 * x-authenticated: true
 * parameters:
 *   - name: id
@@ -15,13 +14,13 @@
 *       type: string
 *   - name: variant_id
 *     in: path
- *     description: The product's variant id.
+ *     description: The products variant's ID.
 *     required: true
 *     schema:
 *       type: string
 *   - name: inventory_item_id
 *     in: path
- *     description: The product's inventory item id.
+ *     description: The inventory item's ID.
 *     required: true
 *     schema:
 *       type: string
@@ -93,11 +93,12 @@
 *             object:
 *               type: string
 *               title: object
- *               description: The promotion's object.
+ *               description: The name of the deleted object.
 *               default: "promotion"
 *             deleted:
 *               type: boolean
 *               title: deleted
- *               description: The promotion's deleted.
+ *               description: Whether the promotion was deleted.
 *             parent:
 *               type: object
 *               description: The promotion's parent.
@@ -93,11 +93,12 @@
 *             object:
 *               type: string
 *               title: object
- *               description: The refund reason's object.
+ *               description: The name of the deleted object.
 *               default: "refund_reason"
 *             deleted:
 *               type: boolean
 *               title: deleted
- *               description: The refund reason's deleted.
+ *               description: Whether the refund reason was deleted.
 *             parent:
 *               type: object
 *               description: The refund reason's parent.
@@ -93,11 +93,12 @@
 *             object:
 *               type: string
 *               title: object
- *               description: The region's object.
+ *               description: The name of the deleted object.
 *               default: "region"
 *             deleted:
 *               type: boolean
 *               title: deleted
- *               description: The region's deleted.
+ *               description: Whether the region was deleted.
 *             parent:
 *               type: object
 *               description: The region's parent.
@@ -93,11 +93,12 @@
 *             object:
 *               type: string
 *               title: object
- *               description: The reservation's object.
+ *               description: The name of the deleted object.
 *               default: "reservation"
 *             deleted:
 *               type: boolean
 *               title: deleted
- *               description: The reservation's deleted.
+ *               description: Whether the reservation was deleted.
 *             parent:
 *               type: object
 *               description: The reservation's parent.
@@ -93,11 +93,12 @@
 *             object:
 *               type: string
 *               title: object
- *               description: The return reason's object.
+ *               description: The name of the deleted object.
 *               default: "return_reason"
 *             deleted:
 *               type: boolean
 *               title: deleted
- *               description: The return reason's deleted.
+ *               description: Whether the return reason was deleted.
 *             parent:
 *               type: object
 *               description: The return reason's parent.
@@ -1,9 +1,15 @@
 /**
 * @oas [delete] /admin/returns/{id}/dismiss-items/{action_id}
 * operationId: DeleteReturnsIdDismissItemsAction_id
- * summary: Remove Dismiss Items from Return
+ * summary: Remove Damaged Item from Return
- * description: Remove a list of dismiss items from a return. This doesn't delete
+ * x-sidebar-summary: Remove Damaged Item
- *   the Dismiss Item, only the association between the Dismiss Item and the
+ * description: >
 *   Remove a damaged item, whose quantity is to be dismissed, in the return by the ID of the 
 *   item's `RECEIVE_DAMAGED_RETURN_ITEM` 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.
 *   return.
 * x-authenticated: true
 * parameters:
@@ -15,7 +21,7 @@
 *       type: string
 *   - name: action_id
 *     in: path
- *     description: The return's action id.
+ *     description: The ID of the damaged item's `RECEIVE_DAMAGED_RETURN_ITEM` action.
 *     required: true
 *     schema:
 *       type: string
@@ -1,9 +1,15 @@
 /**
 * @oas [delete] /admin/returns/{id}/receive-items/{action_id}
 * operationId: DeleteReturnsIdReceiveItemsAction_id
- * summary: Remove Receive Items from Return
+ * summary: Remove a Received Item from Return
- * description: Remove a list of receive items from a return. This doesn't delete
+ * x-sidebar-summary: Remove Received Item
- *   the Receive Item, only the association between the Receive Item and the
+ * description: >
 *   Remove an item marked as received in the return by the ID of the 
 *   item's `RECEIVE_RETURN_ITEM` 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.
 *   return.
 * x-authenticated: true
 * parameters:
@@ -15,7 +21,7 @@
 *       type: string
 *   - name: action_id
 *     in: path
- *     description: The return's action id.
+ *     description: The ID of the received item's `RECEIVE_RETURN_ITEM` action.
 *     required: true
 *     schema:
 *       type: string
@@ -1,9 +1,8 @@
 /**
 * @oas [delete] /admin/returns/{id}/receive
 * operationId: DeleteReturnsIdReceive
- * summary: Remove Receives from Return
+ * summary: Cancel Return Receival
- * description: Remove a list of receives from a return. This doesn't delete the
+ * description: Cancel the receival process previously started, and hasn't been confirmed, of a return.
 *   Receive, only the association between the Receive and the return.
 * x-authenticated: true
 * parameters:
 *   - name: id
@@ -94,11 +93,12 @@
 *             object:
 *               type: string
 *               title: object
- *               description: The return's object.
+ *               description: The name of the returned object.
 *               default: "return"
 *             deleted:
 *               type: boolean
 *               title: deleted
- *               description: The return's deleted.
+ *               description: Whether the return was deleted.
 *             parent:
 *               type: object
 *               description: The return's parent.
@@ -1,9 +1,15 @@
 /**
 * @oas [delete] /admin/returns/{id}/request-items/{action_id}
 * operationId: DeleteReturnsIdRequestItemsAction_id
- * summary: Remove Request Items from Return
+ * summary: Remove Item from Return
- * description: Remove a list of request items from a return. This doesn't delete
+ * x-sidebar-summary: Remove Item
- *   the Request Item, only the association between the Request Item and the
+ * description: >
 *   Remove an item in the return by the ID of the 
 *   item's `RETURN_ITEM` 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.
 *   return.
 * x-authenticated: true
 * parameters:
@@ -15,7 +21,7 @@
 *       type: string
 *   - name: action_id
 *     in: path
- *     description: The return's action id.
+ *     description: The ID of the item's `RETURN_ITEM` action.
 *     required: true
 *     schema:
 *       type: string
@@ -1,9 +1,8 @@
 /**
 * @oas [delete] /admin/returns/{id}/request
 * operationId: DeleteReturnsIdRequest
- * summary: Remove Requests from Return
+ * summary: Cancel Return Request
- * description: Remove a list of requests from a return. This doesn't delete the
+ * description: Cancel a requested return.
 *   Request, only the association between the Request and the return.
 * x-authenticated: true
 * parameters:
 *   - name: id
@@ -94,11 +93,12 @@
 *             object:
 *               type: string
 *               title: object
- *               description: The return's object.
+ *               description: The name of the deleted object.
 *               default: "return"
 *             deleted:
 *               type: boolean
 *               title: deleted
- *               description: The return's deleted.
+ *               description: Whether the return was deleted.
 *             parent:
 *               type: object
 *               description: The return's parent.