docs: create docs workspace (#5174)
* docs: migrate ui docs to docs universe * created yarn workspace * added eslint and tsconfig configurations * fix eslint configurations * fixed eslint configurations * shared tailwind configurations * added shared ui package * added more shared components * migrating more components * made details components shared * move InlineCode component * moved InputText * moved Loading component * Moved Modal component * moved Select components * Moved Tooltip component * moved Search components * moved ColorMode provider * Moved Notification components and providers * used icons package * use UI colors in api-reference * moved Navbar component * used Navbar and Search in UI docs * added Feedback to UI docs * general enhancements * fix color mode * added copy colors file from ui-preset * added features and enhancements to UI docs * move Sidebar component and provider * general fixes and preparations for deployment * update docusaurus version * adjusted versions * fix output directory * remove rootDirectory property * fix yarn.lock * moved code component * added vale for all docs MD and MDX * fix tests * fix vale error * fix deployment errors * change ignore commands * add output directory * fix docs test * general fixes * content fixes * fix announcement script * added changeset * fix vale checks * added nofilter option * fix vale error
This commit is contained in:
Shahed Nasser
GitHub
336
www/apps/api-reference/specs/store/openapi.yaml
Normal file
336
www/apps/api-reference/specs/store/openapi.yaml
Normal file
@@ -0,0 +1,336 @@
|
||||
openapi: 3.0.0
|
||||
info:
|
||||
version: 1.0.0
|
||||
title: Medusa Storefront API
|
||||
license:
|
||||
name: MIT
|
||||
url: https://github.com/medusajs/medusa/blob/master/LICENSE
|
||||
tags:
|
||||
- name: Auth
|
||||
description: >
|
||||
Authentication endpoints allow customers to manage their session, such as
|
||||
login or log out.
|
||||
|
||||
When a customer is logged in, the cookie header is set indicating the
|
||||
customer's login session.
|
||||
externalDocs:
|
||||
description: How to implement customer profiles in your storefront
|
||||
url: >-
|
||||
https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles
|
||||
- name: Carts
|
||||
description: >
|
||||
A cart is a virtual shopping bag that customers can use to add items they
|
||||
want to purchase.
|
||||
|
||||
A cart is then used to checkout and place an order.
|
||||
externalDocs:
|
||||
description: How to implement cart functionality in your storefront
|
||||
url: >-
|
||||
https://docs.medusajs.com/modules/carts-and-checkout/storefront/implement-cart
|
||||
- name: Customers
|
||||
description: >
|
||||
A customer can register and manage their information such as addresses,
|
||||
orders, payment methods, and more.
|
||||
externalDocs:
|
||||
description: How to implement customer profiles in your storefront
|
||||
url: >-
|
||||
https://docs.medusajs.com/modules/customers/storefront/implement-customer-profiles
|
||||
- name: Gift Cards
|
||||
description: >
|
||||
Customers can use gift cards during checkout to deduct the gift card's
|
||||
balance from the checkout total.
|
||||
|
||||
The Gift Card endpoints allow retrieving a gift card's details by its
|
||||
code. A gift card can be applied to a cart using the Carts endpoints.
|
||||
externalDocs:
|
||||
description: How to use gift cards in a storefront
|
||||
url: https://docs.medusajs.com/modules/gift-cards/storefront/use-gift-cards
|
||||
- name: Orders
|
||||
description: >
|
||||
Orders are purchases made by customers, typically through a storefront.
|
||||
|
||||
Orders are placed and created using the Carts endpoints. The Orders
|
||||
endpoints allow retrieving and claiming orders.
|
||||
externalDocs:
|
||||
description: How to retrieve order details in a storefront
|
||||
url: >-
|
||||
https://docs.medusajs.com/modules/orders/storefront/retrieve-order-details
|
||||
- name: Order Edits
|
||||
description: >
|
||||
Order edits are changes made to items in an order such as adding, updating
|
||||
their quantity, or deleting them. Order edits are created by the admin.
|
||||
|
||||
A customer can review order edit requests created by an admin and confirm
|
||||
or decline them.
|
||||
externalDocs:
|
||||
description: How to handle order edits in a storefront
|
||||
url: https://docs.medusajs.com/modules/orders/storefront/handle-order-edits
|
||||
- name: Payment Collections
|
||||
description: >
|
||||
A payment collection is useful for managing additional payments, such as
|
||||
for Order Edits, or installment payments.
|
||||
- name: Products
|
||||
description: >
|
||||
Products are saleable items in a store. This also includes [saleable gift
|
||||
cards](https://docs.medusajs.com/modules/gift-cards/storefront/use-gift-cards)
|
||||
in a store.
|
||||
|
||||
Using these endpoints, 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
|
||||
- name: Product Variants
|
||||
description: >
|
||||
Product variants are the actual salable item in your store. Each variant
|
||||
is a combination of the different option values available on the product.
|
||||
- name: Product Categories
|
||||
description: >
|
||||
Products can be categoriezed into categories. A product can be associated
|
||||
more than one category.
|
||||
|
||||
Using these endpoints, you can list or retrieve a category's details and
|
||||
products.
|
||||
externalDocs:
|
||||
description: How to use product categories in a storefront
|
||||
url: https://docs.medusajs.com/modules/products/storefront/use-categories
|
||||
- name: Product Collections
|
||||
description: >
|
||||
A product collection is used to organize products for different purposes
|
||||
such as marketing or discount purposes. For example, you can create a
|
||||
Summer Collection.
|
||||
|
||||
Using these endpoints, 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.
|
||||
Products can have more than one tag, and products can share tags.
|
||||
- name: Product Types
|
||||
description: |
|
||||
Product types are string values that can be used to filter products by.
|
||||
Products can have more than one tag, and products can share types.
|
||||
- name: Regions
|
||||
description: >
|
||||
Regions are different countries or geographical regions that the commerce
|
||||
store serves customers in.
|
||||
|
||||
Customers can choose what region they're in, which can be used to change
|
||||
the prices shown based on the region and its currency.
|
||||
externalDocs:
|
||||
description: How to use regions in a storefront
|
||||
url: >-
|
||||
https://docs.medusajs.com/modules/regions-and-currencies/storefront/use-regions
|
||||
- name: Returns
|
||||
description: |
|
||||
A return can be created by a customer to return items in an order.
|
||||
externalDocs:
|
||||
description: How to create a return in a storefront
|
||||
url: https://docs.medusajs.com/modules/orders/storefront/create-return
|
||||
- name: Return Reasons
|
||||
description: >
|
||||
Return reasons are key-value pairs that are used to specify why an order
|
||||
return is being created.
|
||||
- name: Shipping Options
|
||||
description: >
|
||||
A shipping option is used to define the available shipping methods during
|
||||
checkout or when creating a return.
|
||||
externalDocs:
|
||||
description: Shipping Option architecture
|
||||
url: >-
|
||||
https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-option
|
||||
- name: Swaps
|
||||
description: >
|
||||
A swap is created by a customer or an admin to exchange an item with a new
|
||||
one.
|
||||
|
||||
Creating a swap implicitely includes creating a return for the item being
|
||||
exchanged.
|
||||
externalDocs:
|
||||
description: How to create a swap in a storefront
|
||||
url: https://docs.medusajs.com/modules/orders/storefront/create-swap
|
||||
servers:
|
||||
- url: https://api.medusa-commerce.com
|
||||
paths:
|
||||
/store/auth:
|
||||
$ref: paths/store_auth.yaml
|
||||
/store/auth/{email}:
|
||||
$ref: paths/store_auth_{email}.yaml
|
||||
/store/carts:
|
||||
$ref: paths/store_carts.yaml
|
||||
/store/carts/{id}:
|
||||
$ref: paths/store_carts_{id}.yaml
|
||||
/store/carts/{id}/complete:
|
||||
$ref: paths/store_carts_{id}_complete.yaml
|
||||
/store/carts/{id}/discounts/{code}:
|
||||
$ref: paths/store_carts_{id}_discounts_{code}.yaml
|
||||
/store/carts/{id}/line-items:
|
||||
$ref: paths/store_carts_{id}_line-items.yaml
|
||||
/store/carts/{id}/line-items/{line_id}:
|
||||
$ref: paths/store_carts_{id}_line-items_{line_id}.yaml
|
||||
/store/carts/{id}/payment-session:
|
||||
$ref: paths/store_carts_{id}_payment-session.yaml
|
||||
/store/carts/{id}/payment-sessions:
|
||||
$ref: paths/store_carts_{id}_payment-sessions.yaml
|
||||
/store/carts/{id}/payment-sessions/{provider_id}:
|
||||
$ref: paths/store_carts_{id}_payment-sessions_{provider_id}.yaml
|
||||
/store/carts/{id}/payment-sessions/{provider_id}/refresh:
|
||||
$ref: paths/store_carts_{id}_payment-sessions_{provider_id}_refresh.yaml
|
||||
/store/carts/{id}/shipping-methods:
|
||||
$ref: paths/store_carts_{id}_shipping-methods.yaml
|
||||
/store/carts/{id}/taxes:
|
||||
$ref: paths/store_carts_{id}_taxes.yaml
|
||||
/store/collections:
|
||||
$ref: paths/store_collections.yaml
|
||||
/store/collections/{id}:
|
||||
$ref: paths/store_collections_{id}.yaml
|
||||
/store/customers:
|
||||
$ref: paths/store_customers.yaml
|
||||
/store/customers/me:
|
||||
$ref: paths/store_customers_me.yaml
|
||||
/store/customers/me/addresses:
|
||||
$ref: paths/store_customers_me_addresses.yaml
|
||||
/store/customers/me/addresses/{address_id}:
|
||||
$ref: paths/store_customers_me_addresses_{address_id}.yaml
|
||||
/store/customers/me/orders:
|
||||
$ref: paths/store_customers_me_orders.yaml
|
||||
/store/customers/me/payment-methods:
|
||||
$ref: paths/store_customers_me_payment-methods.yaml
|
||||
/store/customers/password-reset:
|
||||
$ref: paths/store_customers_password-reset.yaml
|
||||
/store/customers/password-token:
|
||||
$ref: paths/store_customers_password-token.yaml
|
||||
/store/gift-cards/{code}:
|
||||
$ref: paths/store_gift-cards_{code}.yaml
|
||||
/store/order-edits/{id}:
|
||||
$ref: paths/store_order-edits_{id}.yaml
|
||||
/store/order-edits/{id}/complete:
|
||||
$ref: paths/store_order-edits_{id}_complete.yaml
|
||||
/store/order-edits/{id}/decline:
|
||||
$ref: paths/store_order-edits_{id}_decline.yaml
|
||||
/store/orders:
|
||||
$ref: paths/store_orders.yaml
|
||||
/store/orders/batch/customer/token:
|
||||
$ref: paths/store_orders_batch_customer_token.yaml
|
||||
/store/orders/cart/{cart_id}:
|
||||
$ref: paths/store_orders_cart_{cart_id}.yaml
|
||||
/store/orders/customer/confirm:
|
||||
$ref: paths/store_orders_customer_confirm.yaml
|
||||
/store/orders/{id}:
|
||||
$ref: paths/store_orders_{id}.yaml
|
||||
/store/payment-collections/{id}:
|
||||
$ref: paths/store_payment-collections_{id}.yaml
|
||||
/store/payment-collections/{id}/sessions:
|
||||
$ref: paths/store_payment-collections_{id}_sessions.yaml
|
||||
/store/payment-collections/{id}/sessions/batch:
|
||||
$ref: paths/store_payment-collections_{id}_sessions_batch.yaml
|
||||
/store/payment-collections/{id}/sessions/batch/authorize:
|
||||
$ref: paths/store_payment-collections_{id}_sessions_batch_authorize.yaml
|
||||
/store/payment-collections/{id}/sessions/{session_id}:
|
||||
$ref: paths/store_payment-collections_{id}_sessions_{session_id}.yaml
|
||||
/store/payment-collections/{id}/sessions/{session_id}/authorize:
|
||||
$ref: paths/store_payment-collections_{id}_sessions_{session_id}_authorize.yaml
|
||||
/store/product-categories:
|
||||
$ref: paths/store_product-categories.yaml
|
||||
/store/product-categories/{id}:
|
||||
$ref: paths/store_product-categories_{id}.yaml
|
||||
/store/product-tags:
|
||||
$ref: paths/store_product-tags.yaml
|
||||
/store/product-types:
|
||||
$ref: paths/store_product-types.yaml
|
||||
/store/products:
|
||||
$ref: paths/store_products.yaml
|
||||
/store/products/search:
|
||||
$ref: paths/store_products_search.yaml
|
||||
/store/products/{id}:
|
||||
$ref: paths/store_products_{id}.yaml
|
||||
/store/regions:
|
||||
$ref: paths/store_regions.yaml
|
||||
/store/regions/{id}:
|
||||
$ref: paths/store_regions_{id}.yaml
|
||||
/store/return-reasons:
|
||||
$ref: paths/store_return-reasons.yaml
|
||||
/store/return-reasons/{id}:
|
||||
$ref: paths/store_return-reasons_{id}.yaml
|
||||
/store/returns:
|
||||
$ref: paths/store_returns.yaml
|
||||
/store/shipping-options:
|
||||
$ref: paths/store_shipping-options.yaml
|
||||
/store/shipping-options/{cart_id}:
|
||||
$ref: paths/store_shipping-options_{cart_id}.yaml
|
||||
/store/swaps:
|
||||
$ref: paths/store_swaps.yaml
|
||||
/store/swaps/{cart_id}:
|
||||
$ref: paths/store_swaps_{cart_id}.yaml
|
||||
/store/variants:
|
||||
$ref: paths/store_variants.yaml
|
||||
/store/variants/{id}:
|
||||
$ref: paths/store_variants_{id}.yaml
|
||||
components:
|
||||
securitySchemes:
|
||||
cookie_auth:
|
||||
type: apiKey
|
||||
x-displayName: Cookie Session ID
|
||||
in: cookie
|
||||
name: connect.sid
|
||||
description: >
|
||||
Use a cookie session to send authenticated requests.
|
||||
|
||||
|
||||
### How to Obtain the Cookie Session
|
||||
|
||||
|
||||
If you're sending requests through a browser, using JS Client, or using
|
||||
tools like Postman, the cookie session should be automatically set when
|
||||
the customer is logged in.
|
||||
|
||||
|
||||
If you're sending requests using cURL, you must set the Session ID in
|
||||
the cookie manually.
|
||||
|
||||
|
||||
To do that, send a request to [authenticate the
|
||||
customer](#tag/Auth/operation/PostAuth) and pass the cURL option `-v`:
|
||||
|
||||
|
||||
```bash
|
||||
|
||||
curl -v --location --request POST 'https://medusa-url.com/store/auth' \
|
||||
|
||||
--header 'Content-Type: application/json' \
|
||||
|
||||
--data-raw '{
|
||||
"email": "user@example.com",
|
||||
"password": "supersecret"
|
||||
}'
|
||||
|
||||
```
|
||||
|
||||
|
||||
The headers will be logged in the terminal as well as the response. You
|
||||
should find in the headers a Cookie header similar to this:
|
||||
|
||||
|
||||
```bash
|
||||
|
||||
Set-Cookie:
|
||||
connect.sid=s%3A2Bu8BkaP9JUfHu9rG59G16Ma0QZf6Gj1.WT549XqX37PN8n0OecqnMCq798eLjZC5IT7yiDCBHPM;
|
||||
|
||||
```
|
||||
|
||||
|
||||
Copy the value after `connect.sid` (without the `;` at the end) and pass
|
||||
it as a cookie in subsequent requests as the following:
|
||||
|
||||
|
||||
```bash
|
||||
|
||||
curl --location --request GET
|
||||
'https://medusa-url.com/store/customers/me/orders' \
|
||||
|
||||
--header 'Cookie: connect.sid={sid}'
|
||||
|
||||
```
|
||||
|
||||
|
||||
Where `{sid}` is the value of `connect.sid` that you copied.
|
||||
Reference in New Issue
Block a user