oas: [13/n] improve admin oas (#8971)

Improve the OAS of admin API routes [13/n]
This commit is contained in:
Shahed Nasser
2024-09-03 16:59:37 +00:00
committed by GitHub
parent ff623f8b00
commit f47f1aff49
20 changed files with 144 additions and 93 deletions
@@ -4,7 +4,7 @@
* summary: Remove a Received Item from Return * summary: Remove a Received Item from Return
* x-sidebar-summary: Remove Received Item * x-sidebar-summary: Remove Received Item
* description: | * description: |
* Remove an item marked as received in the return by the ID of the item's `RECEIVE_RETURN_ITEM` action. * Remove a received item 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. * 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 * x-authenticated: true
@@ -4,7 +4,7 @@
* summary: Remove Item from Return * summary: Remove Item from Return
* x-sidebar-summary: Remove Item * x-sidebar-summary: Remove Item
* description: | * description: |
* Remove an item in the return by the ID of the item's `RETURN_ITEM` action. * Remove a requested item to be returned 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. * 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 * x-authenticated: true
@@ -2,7 +2,7 @@
* @oas [post] /admin/returns * @oas [post] /admin/returns
* operationId: PostReturns * operationId: PostReturns
* summary: Create Return * summary: Create Return
* description: Create a return. * description: Create a return. The return can later be requested or confirmed.
* x-authenticated: true * x-authenticated: true
* parameters: * parameters:
* - name: expand * - name: expand
@@ -1,8 +1,9 @@
/** /**
* @oas [post] /admin/returns/{id}/dismiss-items * @oas [post] /admin/returns/{id}/dismiss-items
* operationId: PostReturnsIdDismissItems * operationId: PostReturnsIdDismissItems
* summary: Add Dismiss Items to Return * summary: Add Damaged Items to Return
* description: Add a list of dismiss items to a return. * x-sidebar-summary: Add Damaged Items
* description: Add damaged items, whose quantity is to be dismissed, to a return. These items will have the action `RECEIVE_DAMAGED_RETURN_ITEM`.
* x-authenticated: true * x-authenticated: true
* parameters: * parameters:
* - name: id * - name: id
@@ -1,8 +1,12 @@
/** /**
* @oas [post] /admin/returns/{id}/dismiss-items/{action_id} * @oas [post] /admin/returns/{id}/dismiss-items/{action_id}
* operationId: PostReturnsIdDismissItemsAction_id * operationId: PostReturnsIdDismissItemsAction_id
* summary: Add Dismiss Items to Return * summary: Update Damaged Item of Return
* description: Add a list of dismiss items to a return. * x-sidebar-summary: Update Damaged Item
* description: |
* Update 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 * x-authenticated: true
* parameters: * parameters:
* - name: id * - name: id
@@ -13,7 +17,7 @@
* type: string * type: string
* - name: action_id * - name: action_id
* in: path * in: path
* description: The return's action id. * description: The ID of the damaged item's `RECEIVE_DAMAGED_RETURN_ITEM` action.
* required: true * required: true
* schema: * schema:
* type: string * type: string
@@ -1,8 +1,9 @@
/** /**
* @oas [post] /admin/returns/{id}/receive-items * @oas [post] /admin/returns/{id}/receive-items
* operationId: PostReturnsIdReceiveItems * operationId: PostReturnsIdReceiveItems
* summary: Add Receive Items to Return * summary: Add Received Items to Return
* description: Add a list of receive items to a return. * x-sidebar-summary: Add Received Items
* description: Add received items in a return. These items will have the action `RECEIVE_RETURN_ITEM`.
* x-authenticated: true * x-authenticated: true
* parameters: * parameters:
* - name: id * - name: id
@@ -1,8 +1,12 @@
/** /**
* @oas [post] /admin/returns/{id}/receive-items/{action_id} * @oas [post] /admin/returns/{id}/receive-items/{action_id}
* operationId: PostReturnsIdReceiveItemsAction_id * operationId: PostReturnsIdReceiveItemsAction_id
* summary: Add Receive Items to Return * summary: Update a Received Item in a Return
* description: Add a list of receive items to a return. * x-sidebar-summary: Update Received Item
* description: |
* Update a received item 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 * x-authenticated: true
* parameters: * parameters:
* - name: id * - name: id
@@ -13,7 +17,7 @@
* type: string * type: string
* - name: action_id * - name: action_id
* in: path * in: path
* description: The return's action id. * description: The ID of the received item's `RECEIVE_RETURN_ITEM` action.
* required: true * required: true
* schema: * schema:
* type: string * type: string
@@ -1,8 +1,8 @@
/** /**
* @oas [post] /admin/returns/{id}/receive * @oas [post] /admin/returns/{id}/receive
* operationId: PostReturnsIdReceive * operationId: PostReturnsIdReceive
* summary: Add Receives to Return * summary: Start Return Receival
* description: Add a list of receives to a return. * description: Start a return receival process to be later confirmed using the `/admin/returns/:id/receive/confirm` API route.
* x-authenticated: true * x-authenticated: true
* parameters: * parameters:
* - name: id * - name: id
@@ -1,8 +1,10 @@
/** /**
* @oas [post] /admin/returns/{id}/receive/confirm * @oas [post] /admin/returns/{id}/receive/confirm
* operationId: PostReturnsIdReceiveConfirm * operationId: PostReturnsIdReceiveConfirm
* summary: Add Confirms to Return * summary: Confirm Return Receival
* description: Add a list of confirms to a return. * description: >
* Confirm that a return has been received. This updates the quantity of the items received, if not damaged, and
* reflects the changes on the order.
* x-authenticated: true * x-authenticated: true
* parameters: * parameters:
* - name: id * - name: id
@@ -1,8 +1,9 @@
/** /**
* @oas [post] /admin/returns/{id}/request-items * @oas [post] /admin/returns/{id}/request-items
* operationId: PostReturnsIdRequestItems * operationId: PostReturnsIdRequestItems
* summary: Add Request Items to Return * summary: Add Requested Items to Return
* description: Add a list of request items to a return. * x-sidebar-summary: Add Items
* description: Add items that are requested to be returned. These items will have the action `RETURN_ITEM`.
* x-authenticated: true * x-authenticated: true
* parameters: * parameters:
* - name: id * - name: id
@@ -1,8 +1,12 @@
/** /**
* @oas [post] /admin/returns/{id}/request-items/{action_id} * @oas [post] /admin/returns/{id}/request-items/{action_id}
* operationId: PostReturnsIdRequestItemsAction_id * operationId: PostReturnsIdRequestItemsAction_id
* summary: Add Request Items to Return * summary: Update Requested Item in Return
* description: Add a list of request items to a return. * x-sidebar-summary: Update Requested Item
* description: |
* Update a requested item to be returned 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 * x-authenticated: true
* parameters: * parameters:
* - name: id * - name: id
@@ -13,7 +17,7 @@
* type: string * type: string
* - name: action_id * - name: action_id
* in: path * in: path
* description: The return's action id. * description: The ID of the item's `RETURN_ITEM` action.
* required: true * required: true
* schema: * schema:
* type: string * type: string
@@ -1,8 +1,10 @@
/** /**
* @oas [post] /admin/returns/{id}/request * @oas [post] /admin/returns/{id}/request
* operationId: PostReturnsIdRequest * operationId: PostReturnsIdRequest
* summary: Add Requests to Return * summary: Confirm Return Request
* description: Add a list of requests to a return. * description: >
* Confirm a requested return. The changes are applied on the inventory quantity and the order only after the
* return has been confirmed as received using the `/admin/returns/:id/received/confirm`.
* x-authenticated: true * x-authenticated: true
* parameters: * parameters:
* - name: id * - name: id
@@ -1,8 +1,9 @@
/** /**
* @oas [post] /admin/returns/{id}/shipping-method * @oas [post] /admin/returns/{id}/shipping-method
* operationId: PostReturnsIdShippingMethod * operationId: PostReturnsIdShippingMethod
* summary: Add Shipping Methods to Return * summary: Add a Shipping Method to a Return
* description: Add a list of shipping methods to a return. * x-sidebar-summary: Add Shipping Method
* description: Add a shipping method to a return. The shipping method will have a `SHIPPING_ADD` action.
* x-authenticated: true * x-authenticated: true
* parameters: * parameters:
* - name: id * - name: id
@@ -1,8 +1,12 @@
/** /**
* @oas [post] /admin/returns/{id}/shipping-method/{action_id} * @oas [post] /admin/returns/{id}/shipping-method/{action_id}
* operationId: PostReturnsIdShippingMethodAction_id * operationId: PostReturnsIdShippingMethodAction_id
* summary: Add Shipping Methods to Return * summary: Update a Shipping Method of a Return
* description: Add a list of shipping methods to a return. * x-sidebar-summary: Update Shipping Method
* description: |
* Update a shipping method of the return by the ID of the item's `SHIPPING_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 * x-authenticated: true
* parameters: * parameters:
* - name: id * - name: id
@@ -13,7 +17,7 @@
* type: string * type: string
* - name: action_id * - name: action_id
* in: path * in: path
* description: The return's action id. * description: The ID of the shipping method's `SHIPPING_ADD` action.
* required: true * required: true
* schema: * schema:
* type: string * type: string
@@ -1,8 +1,9 @@
/** /**
* @oas [post] /admin/sales-channels/{id}/products * @oas [post] /admin/sales-channels/{id}/products
* operationId: PostSalesChannelsIdProducts * operationId: PostSalesChannelsIdProducts
* summary: Add Products to Sales Channel * summary: Manage Products in Sales Channel
* description: Add a list of products to a sales channel. * x-sidebar-summary: Manage Products
* description: Manage products in a sales channel to add or remove them from the channel.
* x-authenticated: true * x-authenticated: true
* parameters: * parameters:
* - name: id * - name: id
@@ -62,22 +63,22 @@
* application/json: * application/json:
* schema: * schema:
* type: object * type: object
* description: SUMMARY * description: The products to add or remove from the channel.
* properties: * properties:
* add: * add:
* type: array * type: array
* description: The sales channel's add. * description: The products to add to the sales channel.
* items: * items:
* type: string * type: string
* title: add * title: add
* description: The add's details. * description: A product's ID.
* remove: * remove:
* type: array * type: array
* description: The sales channel's remove. * description: The products to remove from the sales channel.
* items: * items:
* type: string * type: string
* title: remove * title: remove
* description: The remove's details. * description: A product's ID.
* x-codeSamples: * x-codeSamples:
* - lang: Shell * - lang: Shell
* label: cURL * label: cURL
@@ -62,7 +62,7 @@
* application/json: * application/json:
* schema: * schema:
* type: object * type: object
* description: SUMMARY * description: The properties to update in the shipping option.
* properties: * properties:
* name: * name:
* type: string * type: string
@@ -70,20 +70,25 @@
* description: The shipping option's name. * description: The shipping option's name.
* data: * data:
* type: object * type: object
* description: The shipping option's data. * description: The shipping option's data that is useful for third-party providers.
* externalDocs:
* url: https://docs.medusajs.com/v2/resources/commerce-modules/fulfillment/shipping-option#data-property
* price_type: * price_type:
* type: string * type: string
* description: >
* The type of the shipping option's price. If `calculated`, its price is retrieved by the
* associated fulfillment provider during checkout. If `flat`, its price is set in the `prices` property.
* enum: * enum:
* - calculated * - calculated
* - flat * - flat
* provider_id: * provider_id:
* type: string * type: string
* title: provider_id * title: provider_id
* description: The shipping option's provider id. * description: The ID of the associated fulfillment provider that is used to process the option.
* shipping_profile_id: * shipping_profile_id:
* type: string * type: string
* title: shipping_profile_id * title: shipping_profile_id
* description: The shipping option's shipping profile id. * description: The ID of the shipping profile this shipping option belongs to.
* type: * type:
* type: object * type: object
* description: The shipping option's type. * description: The shipping option's type.
@@ -106,16 +111,16 @@
* description: The type's code. * description: The type's code.
* prices: * prices:
* type: array * type: array
* description: The shipping option's prices. * description: The shipping option's prices. If the `price_type` is `calculated`, pass an empty array.
* items: * items:
* oneOf: * oneOf:
* - type: object * - type: object
* description: The price's prices. * description: The shipping option's price for a currency code.
* properties: * properties:
* id: * id:
* type: string * type: string
* title: id * title: id
* description: The price's ID. * description: The ID of an existing price.
* currency_code: * currency_code:
* type: string * type: string
* title: currency_code * title: currency_code
@@ -125,16 +130,16 @@
* title: amount * title: amount
* description: The price's amount. * description: The price's amount.
* - type: object * - type: object
* description: The price's prices. * description: The shipping option's price for a region.
* properties: * properties:
* id: * id:
* type: string * type: string
* title: id * title: id
* description: The price's ID. * description: The ID of an existing price.
* region_id: * region_id:
* type: string * type: string
* title: region_id * title: region_id
* description: The price's region id. * description: The ID of the associated region.
* amount: * amount:
* type: number * type: number
* title: amount * title: amount
@@ -145,7 +150,7 @@
* items: * items:
* oneOf: * oneOf:
* - type: object * - type: object
* description: The rule's rules. * description: The details of a new shipping option rule.
* required: * required:
* - operator * - operator
* - attribute * - attribute
@@ -153,6 +158,7 @@
* properties: * properties:
* operator: * operator:
* type: string * type: string
* description: The operator used to check whether a rule applies.
* enum: * enum:
* - in * - in
* - eq * - eq
@@ -165,20 +171,23 @@
* attribute: * attribute:
* type: string * type: string
* title: attribute * title: attribute
* description: The rule's attribute. * description: The name of a property or table that the rule applies to.
* example: customer_group
* value: * value:
* oneOf: * oneOf:
* - type: string * - type: string
* title: value * title: value
* description: The rule's value. * description: A value of the attribute that enables this rule.
* example: cusgroup_123
* - type: array * - type: array
* description: The rule's value. * description: Values of the attribute that enable this rule.
* items: * items:
* type: string * type: string
* title: value * title: value
* description: The value's details. * description: A value of the attribute that enables this rule.
* example: cusgroup_123
* - type: object * - type: object
* description: The rule's rules. * description: Update the properties of an existing rule.
* required: * required:
* - id * - id
* - operator * - operator
@@ -191,6 +200,7 @@
* description: The rule's ID. * description: The rule's ID.
* operator: * operator:
* type: string * type: string
* description: The operator used to check whether a rule applies.
* enum: * enum:
* - in * - in
* - eq * - eq
@@ -204,17 +214,21 @@
* type: string * type: string
* title: attribute * title: attribute
* description: The rule's attribute. * description: The rule's attribute.
* description: The name of a property or table that the rule applies to.
* example: customer_group
* value: * value:
* oneOf: * oneOf:
* - type: string * - type: string
* title: value * title: value
* description: The rule's value. * description: A value of the attribute that enables this rule.
* example: cusgroup_123
* - type: array * - type: array
* description: The rule's value. * description: Values of the attribute that enable this rule.
* items: * items:
* type: string * type: string
* title: value * title: value
* description: The value's details. * description: A value of the attribute that enables this rule.
* example: cusgroup_123
* x-codeSamples: * x-codeSamples:
* - lang: Shell * - lang: Shell
* label: cURL * label: cURL
@@ -1,8 +1,9 @@
/** /**
* @oas [post] /admin/shipping-options/{id}/rules/batch * @oas [post] /admin/shipping-options/{id}/rules/batch
* operationId: PostShippingOptionsIdRulesBatch * operationId: PostShippingOptionsIdRulesBatch
* summary: Add Rules to Shipping Option * summary: Manage the Rules of a Shipping Option
* description: Add a list of rules to a shipping option. * x-sidebar-summary: Manage Rules
* description: Manage the rules of a shipping option to create, update, or delete them.
* x-authenticated: true * x-authenticated: true
* parameters: * parameters:
* - name: id * - name: id
@@ -62,14 +63,14 @@
* application/json: * application/json:
* schema: * schema:
* type: object * type: object
* description: SUMMARY * description: The rules to create, update, or delete.
* properties: * properties:
* create: * create:
* type: array * type: array
* description: The shipping option's create. * description: The shipping option rules to create.
* items: * items:
* type: object * type: object
* description: The create's details. * description: A shipping option's details.
* required: * required:
* - operator * - operator
* - attribute * - attribute
@@ -77,6 +78,7 @@
* properties: * properties:
* operator: * operator:
* type: string * type: string
* description: The operator used to check whether a rule applies.
* enum: * enum:
* - in * - in
* - eq * - eq
@@ -89,24 +91,27 @@
* attribute: * attribute:
* type: string * type: string
* title: attribute * title: attribute
* description: The create's attribute. * description: The name of a property or table that the rule applies to.
* example: customer_group
* value: * value:
* oneOf: * oneOf:
* - type: string * - type: string
* title: value * title: value
* description: The create's value. * description: A value of the attribute that enables this rule.
* example: cusgroup_123
* - type: array * - type: array
* description: The create's value. * description: Values of the attribute that enable this rule.
* items: * items:
* type: string * type: string
* title: value * title: value
* description: The value's details. * description: A value of the attribute that enables this rule.
* example: cusgroup_123
* update: * update:
* type: array * type: array
* description: The shipping option's update. * description: The shipping option rules to update.
* items: * items:
* type: object * type: object
* description: The update's details. * description: The properties to update in the shipping option rule.
* required: * required:
* - id * - id
* - operator * - operator
@@ -116,9 +121,10 @@
* id: * id:
* type: string * type: string
* title: id * title: id
* description: The update's ID. * description: The rule's ID.
* operator: * operator:
* type: string * type: string
* description: The operator used to check whether a rule applies.
* enum: * enum:
* - in * - in
* - eq * - eq
@@ -131,25 +137,28 @@
* attribute: * attribute:
* type: string * type: string
* title: attribute * title: attribute
* description: The update's attribute. * description: The name of a property or table that the rule applies to.
* example: customer_group
* value: * value:
* oneOf: * oneOf:
* - type: string * - type: string
* title: value * title: value
* description: The update's value. * description: A value of the attribute that enables this rule.
* example: cusgroup_123
* - type: array * - type: array
* description: The update's value. * description: Values of the attribute that enable this rule.
* items: * items:
* type: string * type: string
* title: value * title: value
* description: The value's details. * description: A value of the attribute that enables this rule.
* example: cusgroup_123
* delete: * delete:
* type: array * type: array
* description: The shipping option's delete. * description: The shipping option rules to delete.
* items: * items:
* type: string * type: string
* title: delete * title: delete
* description: The delete's details. * description: A rule's ID.
* x-codeSamples: * x-codeSamples:
* - lang: Shell * - lang: Shell
* label: cURL * label: cURL
@@ -165,7 +174,7 @@
* application/json: * application/json:
* schema: * schema:
* type: object * type: object
* description: SUMMARY * description: The batch operation's result.
* required: * required:
* - created * - created
* - updated * - updated
@@ -173,17 +182,17 @@
* properties: * properties:
* created: * created:
* type: array * type: array
* description: The shipping option's created. * description: The created shipping option rules.
* items: * items:
* $ref: "#/components/schemas/AdminShippingOptionRule" * $ref: "#/components/schemas/AdminShippingOptionRule"
* updated: * updated:
* type: array * type: array
* description: The shipping option's updated. * description: The updated shipping option rules.
* items: * items:
* $ref: "#/components/schemas/AdminShippingOptionRule" * $ref: "#/components/schemas/AdminShippingOptionRule"
* deleted: * deleted:
* type: object * type: object
* description: The shipping option's deleted. * description: The details of the deleted shipping option rules.
* required: * required:
* - ids * - ids
* - object * - object
@@ -191,15 +200,16 @@
* properties: * properties:
* ids: * ids:
* type: array * type: array
* description: The deleted's ids. * description: The IDs of the deleted shipping option rules.
* items: * items:
* type: string * type: string
* title: ids * title: ids
* description: The id's ids. * description: A shipping option rule's ID.
* object: * object:
* type: string * type: string
* title: object * title: object
* description: The deleted's object. * description: The name of the deleted object.
* default: shipping_option_rule
* deleted: * deleted:
* type: boolean * type: boolean
* title: deleted * title: deleted
@@ -62,7 +62,7 @@
* application/json: * application/json:
* schema: * schema:
* type: object * type: object
* description: SUMMARY * description: The properties to update in the shipping profile.
* required: * required:
* - metadata * - metadata
* properties: * properties:
@@ -1,8 +1,9 @@
/** /**
* @oas [post] /admin/stock-locations/{id}/fulfillment-providers * @oas [post] /admin/stock-locations/{id}/fulfillment-providers
* operationId: PostStockLocationsIdFulfillmentProviders * operationId: PostStockLocationsIdFulfillmentProviders
* summary: Add Fulfillment Providers to Stock Location * summary: Manage Fulfillment Providers of a Stock Location
* description: Add a list of fulfillment providers to a stock location. * x-sidebar-summary: Manage Fulfillment Providers
* description: Manage the fulfillment providers to add or remove them from a stock location.
* x-authenticated: true * x-authenticated: true
* parameters: * parameters:
* - name: id * - name: id
@@ -62,22 +63,22 @@
* application/json: * application/json:
* schema: * schema:
* type: object * type: object
* description: SUMMARY * description: The fulfillment providers to add or remove from the stock location.
* properties: * properties:
* add: * add:
* type: array * type: array
* description: The stock location's add. * description: The fulfillment providers to add to the stock location.
* items: * items:
* type: string * type: string
* title: add * title: add
* description: The add's details. * description: A fulfillment provider's ID.
* remove: * remove:
* type: array * type: array
* description: The stock location's remove. * description: The fulfillment providers to remove from the stock location.
* items: * items:
* type: string * type: string
* title: remove * title: remove
* description: The remove's details. * description: A fulfillment provider's ID.
* x-codeSamples: * x-codeSamples:
* - lang: Shell * - lang: Shell
* label: cURL * label: cURL
@@ -1,8 +1,9 @@
/** /**
* @oas [post] /admin/stock-locations/{id}/fulfillment-sets * @oas [post] /admin/stock-locations/{id}/fulfillment-sets
* operationId: PostStockLocationsIdFulfillmentSets * operationId: PostStockLocationsIdFulfillmentSets
* summary: Add Fulfillment Sets to Stock Location * summary: Add Fulfillment Set to Stock Location
* description: Add a list of fulfillment sets to a stock location. * x-sidebar-summary: Add Fulfillment Set
* description: Create and add a fulfillment set to a stock location.
* x-authenticated: true * x-authenticated: true
* parameters: * parameters:
* - name: id * - name: id
@@ -62,7 +63,7 @@
* application/json: * application/json:
* schema: * schema:
* type: object * type: object
* description: SUMMARY * description: The fulfillment set to create.
* required: * required:
* - name * - name
* - type * - type
@@ -70,11 +71,11 @@
* name: * name:
* type: string * type: string
* title: name * title: name
* description: The stock location's name. * description: The fulfillment set's name.
* type: * type:
* type: string * type: string
* title: type * title: type
* description: The stock location's type. * description: The fulfillment set's type.
* x-codeSamples: * x-codeSamples:
* - lang: Shell * - lang: Shell
* label: cURL * label: cURL