From da05999f13dffd2adcab6a809d0f8b9c816db8a5 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 20 Oct 2023 14:13:44 +0300 Subject: [PATCH] chore(docs): Generated API Reference (#5431) Co-authored-by: shahednasser --- .../schemas/AdminPostProductsProductReq.yaml | 5 +++-- .../components/schemas/AdminPostProductsReq.yaml | 5 +++-- www/apps/api-reference/specs/admin/openapi.yaml | 8 ++++---- .../api-reference/specs/admin/paths/admin_auth.yaml | 2 +- .../specs/admin/paths/admin_batch-jobs.yaml | 2 +- .../admin/paths/admin_batch-jobs_{id}_confirm.yaml | 2 +- .../specs/admin/paths/admin_products.yaml | 2 +- .../StorePostCustomersCustomerAcceptClaimReq.yaml | 4 +++- .../components/schemas/StorePostReturnsReq.yaml | 2 +- .../store/components/schemas/StorePostSwapsReq.yaml | 2 +- www/apps/api-reference/specs/store/openapi.yaml | 12 ++++++------ .../paths/store_customers_me_payment-methods.yaml | 2 +- .../store/paths/store_customers_password-reset.yaml | 2 +- .../store/paths/store_customers_password-token.yaml | 4 ++-- .../store/paths/store_order-edits_{id}_complete.yaml | 2 +- .../paths/store_orders_batch_customer_token.yaml | 2 +- .../specs/store/paths/store_product-categories.yaml | 2 +- .../specs/store/paths/store_products.yaml | 2 +- .../specs/store/paths/store_regions.yaml | 2 +- .../api-reference/specs/store/paths/store_swaps.yaml | 4 ++-- 20 files changed, 36 insertions(+), 32 deletions(-) diff --git a/www/apps/api-reference/specs/admin/components/schemas/AdminPostProductsProductReq.yaml b/www/apps/api-reference/specs/admin/components/schemas/AdminPostProductsProductReq.yaml index 8d21940df0..931a9dd137 100644 --- a/www/apps/api-reference/specs/admin/components/schemas/AdminPostProductsProductReq.yaml +++ b/www/apps/api-reference/specs/admin/components/schemas/AdminPostProductsProductReq.yaml @@ -17,7 +17,7 @@ properties: 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 + image. You can use the upload API Routes to upload the image and obtain a URL. type: array items: @@ -25,7 +25,8 @@ properties: 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. + You can use the upload API Routes to upload the thumbnail and obtain a + URL. type: string handle: description: >- diff --git a/www/apps/api-reference/specs/admin/components/schemas/AdminPostProductsReq.yaml b/www/apps/api-reference/specs/admin/components/schemas/AdminPostProductsReq.yaml index a67430c63b..bfaa84f7dd 100644 --- a/www/apps/api-reference/specs/admin/components/schemas/AdminPostProductsReq.yaml +++ b/www/apps/api-reference/specs/admin/components/schemas/AdminPostProductsReq.yaml @@ -27,7 +27,7 @@ properties: 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 + image. You can use the upload API Routes to upload the image and obtain a URL. type: array items: @@ -35,7 +35,8 @@ properties: 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. + You can use the upload API Routes to upload the thumbnail and obtain a + URL. type: string handle: description: >- diff --git a/www/apps/api-reference/specs/admin/openapi.yaml b/www/apps/api-reference/specs/admin/openapi.yaml index e20c39aed3..0476dcc10c 100644 --- a/www/apps/api-reference/specs/admin/openapi.yaml +++ b/www/apps/api-reference/specs/admin/openapi.yaml @@ -13,8 +13,8 @@ tags: that, they can create an Oauth provider within the plugin that handles the authentication. - The Apps Oauth API Routes allows admins to manage and generate token for an - app using its oauth provider. + The Apps Oauth API Routes allows admins to manage and generate token for + an app using its oauth provider. - name: Auth description: > Authentication API Routes allow admin users to manage their session, such @@ -41,8 +41,8 @@ tags: A store can use unlimited currencies, and each region must be associated with at least one currency. - Currencies are defined within the Medusa backend. Currency API Routes allow - admins to list and update currencies. + Currencies are defined within the Medusa backend. Currency API Routes + allow admins to list and update currencies. externalDocs: description: How to manage currencies url: >- diff --git a/www/apps/api-reference/specs/admin/paths/admin_auth.yaml b/www/apps/api-reference/specs/admin/paths/admin_auth.yaml index 95b61631e7..e2018ecdb5 100644 --- a/www/apps/api-reference/specs/admin/paths/admin_auth.yaml +++ b/www/apps/api-reference/specs/admin/paths/admin_auth.yaml @@ -93,7 +93,7 @@ delete: 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. + functionalities in other API Routes. x-codegen: method: deleteSession x-codeSamples: diff --git a/www/apps/api-reference/specs/admin/paths/admin_batch-jobs.yaml b/www/apps/api-reference/specs/admin/paths/admin_batch-jobs.yaml index a46378c67b..833dc09b64 100644 --- a/www/apps/api-reference/specs/admin/paths/admin_batch-jobs.yaml +++ b/www/apps/api-reference/specs/admin/paths/admin_batch-jobs.yaml @@ -270,7 +270,7 @@ post: 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. + is confirmed, 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 diff --git a/www/apps/api-reference/specs/admin/paths/admin_batch-jobs_{id}_confirm.yaml b/www/apps/api-reference/specs/admin/paths/admin_batch-jobs_{id}_confirm.yaml index aff34fb829..e0b5031b40 100644 --- a/www/apps/api-reference/specs/admin/paths/admin_batch-jobs_{id}_confirm.yaml +++ b/www/apps/api-reference/specs/admin/paths/admin_batch-jobs_{id}_confirm.yaml @@ -3,7 +3,7 @@ post: 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 + is set to `true`. This API Route confirms that the batch job should be executed. x-authenticated: true parameters: diff --git a/www/apps/api-reference/specs/admin/paths/admin_products.yaml b/www/apps/api-reference/specs/admin/paths/admin_products.yaml index 3865833a43..63396230d9 100644 --- a/www/apps/api-reference/specs/admin/paths/admin_products.yaml +++ b/www/apps/api-reference/specs/admin/paths/admin_products.yaml @@ -281,7 +281,7 @@ post: summary: Create a Product x-authenticated: true description: >- - Create a new Product. This endpoint can also be used to create a gift card + 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: diff --git a/www/apps/api-reference/specs/store/components/schemas/StorePostCustomersCustomerAcceptClaimReq.yaml b/www/apps/api-reference/specs/store/components/schemas/StorePostCustomersCustomerAcceptClaimReq.yaml index 1848dbaa95..ce517bc7a5 100644 --- a/www/apps/api-reference/specs/store/components/schemas/StorePostCustomersCustomerAcceptClaimReq.yaml +++ b/www/apps/api-reference/specs/store/components/schemas/StorePostCustomersCustomerAcceptClaimReq.yaml @@ -3,5 +3,7 @@ required: - 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 diff --git a/www/apps/api-reference/specs/store/components/schemas/StorePostReturnsReq.yaml b/www/apps/api-reference/specs/store/components/schemas/StorePostReturnsReq.yaml index 6e7ce06763..bd74058acc 100644 --- a/www/apps/api-reference/specs/store/components/schemas/StorePostReturnsReq.yaml +++ b/www/apps/api-reference/specs/store/components/schemas/StorePostReturnsReq.yaml @@ -24,7 +24,7 @@ properties: reason_id: description: >- The ID of the return reason. Return reasons can be retrieved from - the List Return Reasons endpoint. + the List Return Reasons API Route. type: string note: description: A note to add to the item returned. diff --git a/www/apps/api-reference/specs/store/components/schemas/StorePostSwapsReq.yaml b/www/apps/api-reference/specs/store/components/schemas/StorePostSwapsReq.yaml index 827f3ca2d6..d6aca5a21e 100644 --- a/www/apps/api-reference/specs/store/components/schemas/StorePostSwapsReq.yaml +++ b/www/apps/api-reference/specs/store/components/schemas/StorePostSwapsReq.yaml @@ -25,7 +25,7 @@ properties: reason_id: description: >- The ID of the reason of this return. Return reasons can be retrieved - from the List Return Reasons endpoint. + from the List Return Reasons API Route. type: string note: description: The note to add to the item being swapped. diff --git a/www/apps/api-reference/specs/store/openapi.yaml b/www/apps/api-reference/specs/store/openapi.yaml index 2ec77274e7..eb1e9df52f 100644 --- a/www/apps/api-reference/specs/store/openapi.yaml +++ b/www/apps/api-reference/specs/store/openapi.yaml @@ -49,8 +49,8 @@ tags: description: > Orders are purchases made by customers, typically through a storefront. - Orders are placed and created using the Carts API Routes. The Orders - API Routes allow retrieving and claiming orders. + Orders are placed and created using the Carts API Routes. The Orders API + Routes allow retrieving and claiming orders. externalDocs: description: How to retrieve order details in a storefront url: >- @@ -75,8 +75,8 @@ tags: cards](https://docs.medusajs.com/modules/gift-cards/storefront/use-gift-cards) in a store. - Using these API Routes, you can filter products by categories, collections, - sales channels, and more. + Using these API Routes, you can filter products by categories, + collections, sales channels, and more. externalDocs: description: How to show products in a storefront url: https://docs.medusajs.com/modules/products/storefront/show-products @@ -100,8 +100,8 @@ tags: such as marketing or discount purposes. For example, you can create a Summer Collection. - Using these API Routes, you can list or retrieve a collection's details and - products. + Using these API Routes, you can list or retrieve a collection's details + and products. - name: Product Tags description: | Product tags are string values that can be used to filter products by. diff --git a/www/apps/api-reference/specs/store/paths/store_customers_me_payment-methods.yaml b/www/apps/api-reference/specs/store/paths/store_customers_me_payment-methods.yaml index 9752d88b92..67e16318a8 100644 --- a/www/apps/api-reference/specs/store/paths/store_customers_me_payment-methods.yaml +++ b/www/apps/api-reference/specs/store/paths/store_customers_me_payment-methods.yaml @@ -2,7 +2,7 @@ get: operationId: GetCustomersCustomerPaymentMethods summary: Get Saved Payment Methods description: >- - Retrieve the logged-in customer's saved payment methods. This endpoint only + 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 diff --git a/www/apps/api-reference/specs/store/paths/store_customers_password-reset.yaml b/www/apps/api-reference/specs/store/paths/store_customers_password-reset.yaml index 6aac430500..5961ccda45 100644 --- a/www/apps/api-reference/specs/store/paths/store_customers_password-reset.yaml +++ b/www/apps/api-reference/specs/store/paths/store_customers_password-reset.yaml @@ -3,7 +3,7 @@ post: 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 + 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 diff --git a/www/apps/api-reference/specs/store/paths/store_customers_password-token.yaml b/www/apps/api-reference/specs/store/paths/store_customers_password-token.yaml index df7843813e..21ae415b8e 100644 --- a/www/apps/api-reference/specs/store/paths/store_customers_password-token.yaml +++ b/www/apps/api-reference/specs/store/paths/store_customers_password-token.yaml @@ -2,8 +2,8 @@ post: 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 + 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. diff --git a/www/apps/api-reference/specs/store/paths/store_order-edits_{id}_complete.yaml b/www/apps/api-reference/specs/store/paths/store_order-edits_{id}_complete.yaml index 2ca13e864a..358296f3cc 100644 --- a/www/apps/api-reference/specs/store/paths/store_order-edits_{id}_complete.yaml +++ b/www/apps/api-reference/specs/store/paths/store_order-edits_{id}_complete.yaml @@ -4,7 +4,7 @@ post: 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. + Collection API Routes. externalDocs: description: How to handle order edits in a storefront url: https://docs.medusajs.com/modules/orders/storefront/handle-order-edits diff --git a/www/apps/api-reference/specs/store/paths/store_orders_batch_customer_token.yaml b/www/apps/api-reference/specs/store/paths/store_orders_batch_customer_token.yaml index a28188c0f1..7b321c464b 100644 --- a/www/apps/api-reference/specs/store/paths/store_orders_batch_customer_token.yaml +++ b/www/apps/api-reference/specs/store/paths/store_orders_batch_customer_token.yaml @@ -4,7 +4,7 @@ post: 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. This also emits the event + 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 diff --git a/www/apps/api-reference/specs/store/paths/store_product-categories.yaml b/www/apps/api-reference/specs/store/paths/store_product-categories.yaml index 103b4ac698..780d0cb26f 100644 --- a/www/apps/api-reference/specs/store/paths/store_product-categories.yaml +++ b/www/apps/api-reference/specs/store/paths/store_product-categories.yaml @@ -4,7 +4,7 @@ get: 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 + be paginated. This API Route can also be used to retrieve a product category by its handle. x-featureFlag: product_categories externalDocs: diff --git a/www/apps/api-reference/specs/store/paths/store_products.yaml b/www/apps/api-reference/specs/store/paths/store_products.yaml index c6d9cfe224..d2088223a9 100644 --- a/www/apps/api-reference/specs/store/paths/store_products.yaml +++ b/www/apps/api-reference/specs/store/paths/store_products.yaml @@ -5,7 +5,7 @@ get: 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 diff --git a/www/apps/api-reference/specs/store/paths/store_regions.yaml b/www/apps/api-reference/specs/store/paths/store_regions.yaml index 5d129c1ff9..3541266894 100644 --- a/www/apps/api-reference/specs/store/paths/store_regions.yaml +++ b/www/apps/api-reference/specs/store/paths/store_regions.yaml @@ -3,7 +3,7 @@ get: 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 + `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 diff --git a/www/apps/api-reference/specs/store/paths/store_swaps.yaml b/www/apps/api-reference/specs/store/paths/store_swaps.yaml index 7a6e64878f..12afefc0a8 100644 --- a/www/apps/api-reference/specs/store/paths/store_swaps.yaml +++ b/www/apps/api-reference/specs/store/paths/store_swaps.yaml @@ -6,8 +6,8 @@ post: 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