docs: update endpoints to use file-routing approach (#5397)

- Move the original guides for creating endpoints and middlewares to sub-sections in the Endpoints category.
- Replace existing guides for endpoints and middlewares with the new approach.
- Update all endpoints-related snippets across docs to use this new approach.

packages/medusa/src/api/routes/admin/auth/delete-session.ts

@@ -4,7 +4,7 @@
  * summary: "User Logout"
  * x-authenticated: true
  * description: "Delete the current session for the logged in user. This will only work if you're using Cookie session for authentication. If the API token is still passed in the header,
- * the user is still authorized to perform admin functionalities in other endpoints."
+ * the user is still authorized to perform admin functionalities in other API Routes."
  * x-codegen:
  *   method: deleteSession
  * x-codeSamples:

packages/medusa/src/api/routes/admin/batch/confirm-batch-job.ts

@@ -5,7 +5,7 @@ import { EntityManager } from "typeorm"
  * @oas [post] /admin/batch-jobs/{id}/confirm
  * operationId: "PostBatchJobsBatchJobConfirmProcessing"
  * summary: "Confirm a Batch Job"
- * description: "When a batch job is created, it is not executed automatically if `dry_run` is set to `true`. This endpoint confirms that the batch job should be executed."
+ * description: "When a batch job is created, it is not executed automatically if `dry_run` is set to `true`. This API Route confirms that the batch job should be executed."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the batch job.

packages/medusa/src/api/routes/admin/batch/create-batch-job.ts

@@ -10,7 +10,7 @@ import { validator } from "../../../../utils/validator"
  * operationId: "PostBatchJobs"
  * summary: "Create a Batch Job"
  * description: "Create a Batch Job to be executed asynchronously in the Medusa backend. If `dry_run` is set to `true`, the batch job will not be executed until the it is confirmed,
- *  which can be done using the Confirm Batch Job endpoint."
+ *  which can be done using the Confirm Batch Job API Route."
  * externalDocs:
  *   description: "How to create a batch job"
  *   url: "https://docs.medusajs.com/development/batch-jobs/create#create-batch-job"

packages/medusa/src/api/routes/admin/products/create-product.ts

@@ -54,7 +54,7 @@ import IsolateProductDomainFeatureFlag from "../../../../loaders/feature-flags/i
  * operationId: "PostProducts"
  * summary: "Create a Product"
  * x-authenticated: true
- * description: "Create a new Product. This endpoint can also be used to create a gift card if the `is_giftcard` field is set to `true`."
+ * description: "Create a new Product. This API Route can also be used to create a gift card if the `is_giftcard` field is set to `true`."
  * requestBody:
  *   content:
  *     application/json:
@@ -408,12 +408,12 @@ class ProductVariantReq {
  *     type: boolean
  *     default: true
  *   images:
- *     description: An array of images of the Product. Each value in the array is a URL to the image. You can use the upload endpoints to upload the image and obtain a URL.
+ *     description: An array of images of the Product. Each value in the array is a URL to the image. You can use the upload API Routes to upload the image and obtain a URL.
  *     type: array
  *     items:
  *       type: string
  *   thumbnail:
- *     description: The thumbnail to use for the Product. The value is a URL to the thumbnail. You can use the upload endpoints to upload the thumbnail and obtain a URL.
+ *     description: The thumbnail to use for the Product. The value is a URL to the thumbnail. You can use the upload API Routes to upload the thumbnail and obtain a URL.
  *     type: string
  *   handle:
  *     description: A unique handle to identify the Product by. If not provided, the kebab-case version of the product title will be used. This can be used as a slug in URLs.

packages/medusa/src/api/routes/admin/products/update-product.ts

@@ -434,12 +434,12 @@ class ProductVariantReq {
  *     description: A flag to indicate if discounts can be applied to the Line Items generated from this Product
  *     type: boolean
  *   images:
- *     description: An array of images of the Product. Each value in the array is a URL to the image. You can use the upload endpoints to upload the image and obtain a URL.
+ *     description: An array of images of the Product. Each value in the array is a URL to the image. You can use the upload API Routes to upload the image and obtain a URL.
  *     type: array
  *     items:
  *       type: string
  *   thumbnail:
- *     description: The thumbnail to use for the Product. The value is a URL to the thumbnail. You can use the upload endpoints to upload the thumbnail and obtain a URL.
+ *     description: The thumbnail to use for the Product. The value is a URL to the thumbnail. You can use the upload API Routes to upload the thumbnail and obtain a URL.
  *     type: string
  *   handle:
  *     description: A unique handle to identify the Product by. If not provided, the kebab-case version of the product title will be used. This can be used as a slug in URLs.

packages/medusa/src/api/routes/store/customers/get-payment-methods.ts

@@ -7,7 +7,7 @@ import { PaymentProvider } from "../../../../models"
  * @oas [get] /store/customers/me/payment-methods
  * operationId: GetCustomersCustomerPaymentMethods
  * summary: Get Saved Payment Methods
- * description: "Retrieve the logged-in customer's saved payment methods. This endpoint only works with payment providers created with the deprecated Payment Service interface.
+ * description: "Retrieve the logged-in customer's saved payment methods. This API Route only works with payment providers created with the deprecated Payment Service interface.
  *  The payment methods are saved using the Payment Service's third-party service, and not on the Medusa backend. So, they're retrieved from the third-party service."
  * x-authenticated: true
  * deprecated: true

packages/medusa/src/api/routes/store/customers/reset-password-token.ts

@@ -7,7 +7,7 @@ import { EntityManager } from "typeorm"
  * @oas [post] /store/customers/password-token
  * operationId: PostCustomersCustomerPasswordToken
  * summary: Request Password Reset
- * description: "Create a reset password token to be used in a subsequent Reset Password endpoint. This emits the event `customer.password_reset`. If a notification provider is
+ * description: "Create a reset password token to be used in a subsequent Reset Password API Route. This emits the event `customer.password_reset`. If a notification provider is
  *  installed in the Medusa backend and is configured to handle this event, a notification to the customer, such as an email, may be sent with reset instructions."
  * externalDocs:
  *   description: "How to reset password"

packages/medusa/src/api/routes/store/customers/reset-password.ts

@@ -10,7 +10,7 @@ import { MedusaError } from "medusa-core-utils"
  * @oas [post] /store/customers/password-reset
  * operationId: PostCustomersResetPassword
  * summary: Reset Password
- * description: "Reset a Customer's password using a password token created by a previous request to the Request Password Reset endpoint. If the password token expired,
+ * description: "Reset a Customer's password using a password token created by a previous request to the Request Password Reset API Route. If the password token expired,
  *  you must create a new one."
  * externalDocs:
  *   description: "How to reset password"

packages/medusa/src/api/routes/store/order-edits/complete-order-edit.ts

@@ -12,7 +12,7 @@ import {
  * @oas [post] /store/order-edits/{id}/complete
  * operationId: "PostOrderEditsOrderEditComplete"
  * summary: "Complete an Order Edit"
- * description: "Complete an Order Edit and reflect its changes on the original order. Any additional payment required must be authorized first using the Payment Collection endpoints."
+ * description: "Complete an Order Edit and reflect its changes on the original order. Any additional payment required must be authorized first using the Payment Collection API Routes."
  * externalDocs:
  *   description: "How to handle order edits in a storefront"
  *   url: "https://docs.medusajs.com/modules/orders/storefront/handle-order-edits"

packages/medusa/src/api/routes/store/orders/confirm-order-request.ts

@@ -118,7 +118,7 @@ export default async (req, res) => {
  *   - token
  * properties:
  *   token:
- *     description: "The claim token generated by previous request to the Claim Order endpoint."
+ *     description: "The claim token generated by previous request to the Claim Order API Route."
  *     type: string
  */
 export class StorePostCustomersCustomerAcceptClaimReq {

packages/medusa/src/api/routes/store/orders/request-order.ts

@@ -9,7 +9,7 @@ import { TokenEvents } from "../../../../types/token"
  * @oas [post] /store/orders/batch/customer/token
  * operationId: "PostOrdersCustomerOrderClaim"
  * summary: "Claim Order"
- * description: "Allow the logged-in customer to claim ownership of one or more orders. This generates a token that can be used later on to verify the claim using the endpoint Verify Order Claim.
+ * description: "Allow the logged-in customer to claim ownership of one or more orders. This generates a token that can be used later on to verify the claim using the Verify Order Claim API Route.
  *  This also emits the event `order-update-token.created`. So, if you have a notification provider installed that handles this event and sends the customer a notification, such as an email,
  *  the customer should receive instructions on how to finalize their claim ownership."
  * externalDocs:

packages/medusa/src/api/routes/store/product-categories/list-product-categories.ts

@@ -12,7 +12,7 @@ import { defaultStoreCategoryScope } from "."
  * operationId: "GetProductCategories"
  * summary: "List Product Categories"
  * description: "Retrieve a list of product categories. The product categories can be filtered by fields such as `handle` or `q`. The product categories can also be paginated.
- *  This endpoint can also be used to retrieve a product category by its handle."
+ *  This API Route can also be used to retrieve a product category by its handle."
  * x-featureFlag: "product_categories"
  * externalDocs:
  *   description: "How to retrieve a product category by its handle"

packages/medusa/src/api/routes/store/products/list-products.ts

@@ -32,7 +32,7 @@ import { defaultStoreProductRemoteQueryObject } from "./index"
  * summary: List Products
  * description: |
  *   Retrieves a list of products. The products can be filtered by fields such as `id` or `q`. The products can also be sorted or paginated.
- *   This endpoint can also be used to retrieve a product by its handle.
+ *   This API Route can also be used to retrieve a product by its handle.
  *
  *   For accurate and correct pricing of the products based on the customer's context, it's highly recommended to pass fields such as
  *   `region_id`, `currency_code`, and `cart_id` when available.

packages/medusa/src/api/routes/store/regions/list-regions.ts

@@ -11,7 +11,7 @@ import { validator } from "../../../../utils/validator"
  * @oas [get] /store/regions
  * operationId: GetRegions
  * summary: List Regions
- * description: "Retrieve a list of regions. The regions can be filtered by fields such as `created_at`. The regions can also be paginated. This endpoint is useful to
+ * description: "Retrieve a list of regions. The regions can be filtered by fields such as `created_at`. The regions can also be paginated. This API Route is useful to
  *  show the customer all available regions to choose from."
  * externalDocs:
  *   description: "How to use regions in a storefront"

packages/medusa/src/api/routes/store/returns/create-return.ts

@@ -280,7 +280,7 @@ class Item {
  *           description: The quantity to return.
  *           type: integer
  *         reason_id:
- *           description: The ID of the return reason. Return reasons can be retrieved from the List Return Reasons endpoint.
+ *           description: The ID of the return reason. Return reasons can be retrieved from the List Return Reasons API Route.
  *           type: string
  *         note:
  *           description: A note to add to the item returned.

packages/medusa/src/api/routes/store/swaps/create-swap.ts

@@ -24,7 +24,7 @@ import { validator } from "../../../../utils/validator"
  * summary: Create a Swap
  * description: |
  *   Create a Swap for an Order. This will also create a return and associate it with the swap. If a return shipping option is specified, the return will automatically be fulfilled.
- *   To complete the swap, you must use the Complete Cart endpoint passing it the ID of the swap's cart.
+ *   To complete the swap, you must use the Complete Cart API Route passing it the ID of the swap's cart.
  *
  *   An idempotency key will be generated if none is provided in the header `Idempotency-Key` and added to
  *   the response. If an error occurs during swap creation or the request is interrupted for any reason, the swap creation can be retried by passing the idempotency
@@ -316,7 +316,7 @@ class AdditionalItem {
  *           description: The quantity to return.
  *           type: integer
  *         reason_id:
- *           description: The ID of the reason of this return. Return reasons can be retrieved from the List Return Reasons endpoint.
+ *           description: The ID of the reason of this return. Return reasons can be retrieved from the List Return Reasons API Route.
  *           type: string
  *         note:
  *           description: The note to add to the item being swapped.