asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

chore(medusa-oas-cli,oas-github-ci): remove v2 option + generate v2 by default (#7304)

Browse Source 
* chore(medusa-oas-cli,oas-github-ci): remove v2 option + generate v2 by default

* fixes to changeset

* fix public url path
This commit is contained in:
Shahed Nasser
2024-05-13 17:01:38 +03:00
committed by GitHub
parent 63623422fe
commit 8b2429d24f
10 changed files with 111 additions and 926 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
.changeset/cold-bikes-build.md Normal file
View File

@@ -0,0 +1,9 @@
---
"@medusajs/medusa-oas-cli": major
---
chore(medusa-oas-cli): remove v2 option + generate v2 OAS by default
## Breaking Change
This introduces a breaking change to the `medusa-oas-cli` as it no longer generates OAS for v1 projects. Users using it with Medusa v1 have to use v0.3.x moving forward.

5
.changeset/seven-suits-dream.md Normal file
View File

@@ -0,0 +1,5 @@
---
"@medusajs/oas-github-ci": patch
---
chore(oas-github-ci): remove v2 option

52
.github/workflows/generate-public-references.yml vendored
View File

@@ -10,56 +10,6 @@ on:
types: [published]
jobs:
api:
runs-on: ubuntu-latest
if: ${{ github.event_name == 'release' || github.event.inputs.referenceName == 'all' || github.event.inputs.referenceName == 'api' }}
steps:
- name: Cancel Previous Runs
uses: styfle/cancel-workflow-action@0.11.0
with:
access_token: ${{ github.token }}
- name: Checkout
uses: actions/checkout@v3
with:
token: ${{ secrets.REFERENCE_PAT }}
fetch-depth: 0
- name: Setup Node.js environment
uses: actions/setup-node@v3
with:
node-version: "16.10.0"
cache: "yarn"
- name: Install dependencies
uses: ./.github/actions/cache-deps
with:
extension: reference
- name: Build Packages
run: yarn build
- name: Generate API Reference
run: yarn openapi:generate
- name: Install and Build www/utils dependencies
run: yarn && yarn build
working-directory: www/utils
- name: Generate Changeset
run: "yarn generate:changeset"
working-directory: www/utils/packages/scripts
- name: Create Pull Request
uses: peter-evans/create-pull-request@v4
with:
commit-message: "chore(docs): Generated API Reference"
base: "develop"
title: "chore(docs): Updated API Reference"
labels: "type: chore"
add-paths: www/apps/api-reference/specs
branch: "docs/generate-api-ref"
branch-suffix: "timestamp"
api-v2:
runs-on: ubuntu-latest
if: ${{ github.event_name == 'release' || github.event.inputs.referenceName == 'all' || github.event.inputs.referenceName == 'api' }}
@@ -90,7 +40,7 @@ jobs:
run: yarn build
- name: Generate API Reference (v2)
run: yarn openapi:generate --v2
run: yarn openapi:generate
- name: Install and Build www/utils dependencies
run: yarn && yarn build

4
package.json
View File

@@ -77,8 +77,8 @@
"test:integration:packages": "turbo run test:integration --concurrency=50% --no-daemon --no-cache --force --filter='./packages/*' --filter='./packages/core/*' --filter='./packages/cli/*' --filter='./packages/modules/*' --filter='./packages/modules/providers/*'",
"test:integration:api": "turbo run test:integration:chunk --concurrency=50% --no-daemon --no-cache --force --filter=integration-tests-api",
"test:integration:modules": "turbo run test:integration:chunk --concurrency=50% --no-daemon --no-cache --force --filter=integration-tests-modules",
"openapi:generate": "yarn ./packages/cli/oas/oas-github-ci run ci --with-full-file --v2",
"medusa-oas": "yarn ./packages/cli/oas/medusa-oas-cli run medusa-oas --v2",
"openapi:generate": "yarn ./packages/cli/oas/oas-github-ci run ci --with-full-file",
"medusa-oas": "yarn ./packages/cli/oas/medusa-oas-cli run medusa-oas",
"release:snapshot": "changeset publish --no-git-tags --snapshot --tag snapshot",
"release:next": "chgstangeset publish --no-git-tags --snapshot --tag next",
"version:next": "changeset version --snapshot next",

39
packages/cli/oas/medusa-oas-cli/src/command-oas.ts
View File

@@ -18,14 +18,6 @@ import { isFile } from "./utils/fs-utils"
const medusaPackagePath = path.dirname(
require.resolve("@medusajs/medusa/package.json")
)
// Types package directory
const medusaTypesPath = path.dirname(
require.resolve("@medusajs/types/package.json")
)
// Utils package directory
const medusaUtilsPath = path.dirname(
require.resolve("@medusajs/utils/package.json")
)
const basePath = path.resolve(__dirname, "../")
/**
@@ -53,10 +45,6 @@ export const commandOptions: Option[] = [
"Custom base OAS file to use for swagger-inline."
),
new Option("-F, --force", "Ignore OAS validation and output OAS files."),
new Option(
"--v2",
"Generate OAS files for V2 endpoints. This loads OAS from www/utils/generated/oas-output/operations directory"
),
new Option(
"--local",
"Generate OAS from local files rather than public OAS. This is useful for generating references in the Medusa monorepo."
@@ -117,11 +105,11 @@ export async function execute(cliParams: OptionValues) {
console.log(`🟣 Generating OAS - ${apiType}`)
if (apiType === "combined") {
const adminOAS = !local ? await getPublicOas("admin", v2) : await getOASFromCodebase("admin", v2)
const storeOAS = !local ? await getPublicOas("store", v2) : await getOASFromCodebase("store", v2)
const adminOAS = !local ? await getPublicOas("admin") : await getOASFromCodebase("admin")
const storeOAS = !local ? await getPublicOas("store") : await getOASFromCodebase("store")
oas = await combineOAS(adminOAS, storeOAS)
} else {
oas = !local ? await getPublicOas(apiType, v2) : await getOASFromCodebase(apiType, v2)
oas = !local ? await getPublicOas(apiType) : await getOASFromCodebase(apiType)
}
if (additionalPaths.length || baseFile) {
@@ -146,36 +134,24 @@ export async function execute(cliParams: OptionValues) {
* Methods
*/
async function getOASFromCodebase(
apiType: ApiType,
v2?: boolean
apiType: ApiType
): Promise<OpenAPIObject> {
/**
* OAS output directory
*
* @privateRemark
* This should be the only directory OAS is loaded from for Medusa V2.
* For now, we only use it if the --v2 flag it passed to the CLI tool.
*/
const oasOutputPath = path.resolve(
__dirname, "..", "..", "..", "..", "..", "www", "utils", "generated", "oas-output"
)
const gen = await swaggerInline(
v2 ? [
[
path.resolve(oasOutputPath, "operations", apiType),
path.resolve(oasOutputPath, "schemas"),
// We currently load error schemas from here. If we change
// that in the future, we should change the path.
path.resolve(medusaPackagePath, "dist", "utils/middlewares"),
] : [
path.resolve(medusaTypesPath, "dist"),
path.resolve(medusaUtilsPath, "dist"),
path.resolve(medusaPackagePath, "dist", "models"),
path.resolve(medusaPackagePath, "dist", "types"),
path.resolve(medusaPackagePath, "dist", "api/middlewares"),
path.resolve(medusaPackagePath, "dist", `api/routes/${apiType}`),
],
{
base: path.resolve(oasOutputPath, v2 ? "base-v2" : "base", `${apiType}.oas.base.yaml`),
base: path.resolve(oasOutputPath, "base", `${apiType}.oas.base.yaml`),
format: ".json",
}
)
@@ -184,9 +160,8 @@ async function getOASFromCodebase(
async function getPublicOas(
apiType: ApiType,
v2?: boolean
) {
const url = `https://docs.medusajs.com/api/download/${apiType}?version=${v2 ? "2" : "1"}`
const url = `https://docs.medusajs.com/v2/api/download/${apiType}`
return await OpenAPIParser.parse(url) as OpenAPIObject
}

7
packages/cli/oas/oas-github-ci/scripts/build-openapi.js
View File

@@ -7,11 +7,9 @@ const execa = require("execa")
const isDryRun = process.argv.indexOf("--dry-run") !== -1
const withFullFile = process.argv.indexOf("--with-full-file") !== -1
const v2 = process.argv.indexOf("--v2") !== -1
const basePath = path.resolve(__dirname, `../`)
const repoRootPath = path.resolve(basePath, `../../../../`)
const docsApiPath = v2 ? path.resolve(repoRootPath, "www/apps/api-reference/specs-v2") :
path.resolve(repoRootPath, "www/apps/api-reference/specs")
const docsApiPath = path.resolve(repoRootPath, "www/apps/api-reference/specs")
const run = async () => {
const oasOutDir = isDryRun ? await getTmpDirectory() : docsApiPath
@@ -25,9 +23,6 @@ const run = async () => {
const generateOASSource = async (outDir, apiType) => {
const commandParams = ["oas", `--type=${apiType}`, `--out-dir=${outDir}`, "--local"]
if (v2) {
commandParams.push(`--v2`)
}
const { all: logs } = await execa(
"medusa-oas",
commandParams,

228
www/utils/generated/oas-output/base-v2/admin.oas.base.yaml
View File

@@ -1,228 +0,0 @@
openapi: 3.0.0
info:
version: 2.0.0
title: Medusa Admin API
license:
name: MIT
url: https://github.com/medusajs/medusa/blob/master/LICENSE
tags:
- name: Api Keys
- name: Campaigns
- name: Collections
- name: Currencies
description: >
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.
externalDocs:
description: How to manage currencies
url: https://docs.medusajs.com/modules/regions-and-currencies/admin/manage-currencies
- name: Customer Groups
- name: Customers
description: >
Customers can either be created when they register through the Store APIs,
or created by the admin using the Admin APIs.
externalDocs:
description: How to manage customers
url: https://docs.medusajs.com/modules/customers/admin/manage-customers
- name: Draft Orders
- name: Fulfillment Providers
- name: Fulfillment Sets
- name: Fulfillments
- name: Inventory Items
- name: Invites
description: >
An admin can invite new users to manage their team. This would allow new
users to authenticate as admins and perform admin functionalities.
externalDocs:
description: How to manage invites
url: https://docs.medusajs.com/modules/users/admin/manage-invites
- name: Orders
- name: Payments
- name: Price Lists
- name: Pricing
- name: Product Categories
- name: Product Types
- name: Products
- name: Promotions
x-associatedSchema:
$ref: "#/components/schemas/Promotion"
- name: Regions
description: >
Regions are different countries or geographical regions that the commerce
store serves customers in.
Admins can manage these regions, their providers, and more.
externalDocs:
description: How to manage regions
url: https://docs.medusajs.com/modules/regions-and-currencies/admin/manage-regions
- name: Reservations
- name: Sales Channels
description: >
A sales channel indicates a channel where products can be sold in. For
example, a webshop or a mobile app.
Admins can manage sales channels and the products available in them.
externalDocs:
description: How to manage sales channels
url: https://docs.medusajs.com/modules/sales-channels/admin/manage
- name: Shipping Options
- name: Shipping Profiles
- name: Stock Locations
- name: Stores
- name: Tax Rates
- name: Tax Regions
- name: Uploads
- name: Users
- name: Workflows Executions
servers:
- url: http://localhost:9000
- url: https://api.medusa-commerce.com
paths: {}
components:
responses:
default_error:
description: Default Error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
code: unknown_error
message: An unknown error occurred.
type: unknown_error
invalid_state_error:
description: Invalid State Error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
code: unknown_error
message: The request conflicted with another request. You may retry the request
with the provided Idempotency-Key.
type: QueryRunnerAlreadyReleasedError
invalid_request_error:
description: Invalid Request Error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
code: invalid_request_error
message: Discount with code TEST already exists.
type: duplicate_error
not_found_error:
description: Not Found Error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
message: Entity with id 1 was not found
type: not_found
400_error:
description: Client Error or Multiple Errors
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/Error"
- $ref: "#/components/schemas/MultipleErrors"
examples:
not_allowed:
$ref: "#/components/examples/not_allowed_error"
invalid_data:
$ref: "#/components/examples/invalid_data_error"
MultipleErrors:
$ref: "#/components/examples/multiple_errors"
500_error:
description: Server Error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
examples:
database:
$ref: "#/components/examples/database_error"
unexpected_state:
$ref: "#/components/examples/unexpected_state_error"
invalid_argument:
$ref: "#/components/examples/invalid_argument_error"
default_error:
$ref: "#/components/examples/default_error"
unauthorized:
description: User is not authorized. Must log in first
content:
text/plain:
schema:
type: string
default: Unauthorized
example: Unauthorized
incorrect_credentials:
description: User does not exist or incorrect credentials
content:
text/plain:
schema:
type: string
default: Unauthorized
example: Unauthorized
examples:
not_allowed_error:
summary: Not Allowed Error
value:
message: Discount must be set to dynamic
type: not_allowed
invalid_data_error:
summary: Invalid Data Error
value:
message: first_name must be a string
type: invalid_data
multiple_errors:
summary: Multiple Errors
value:
message: Provided request body contains errors. Please check the data and retry
the request
errors:
- message: first_name must be a string
type: invalid_data
- message: Discount must be set to dynamic
type: not_allowed
database_error:
summary: Database Error
value:
code: api_error
message: An error occured while hashing password
type: database_error
unexpected_state_error:
summary: Unexpected State Error
value:
message: cart.total must be defined
type: unexpected_state
invalid_argument_error:
summary: Invalid Argument Error
value:
message: cart.total must be defined
type: unexpected_state
default_error:
summary: Default Error
value:
code: unknown_error
message: An unknown error occurred.
type: unknown_error
securitySchemes:
api_token:
type: apiKey
x-displayName: API Token
in: header
name: x-medusa-access-token
jwt_token:
type: http
x-displayName: JWT Token
scheme: bearer
cookie_auth:
type: apiKey
in: cookie
name: connect.sid
x-displayName: Cookie Session ID

234
www/utils/generated/oas-output/base-v2/store.oas.base.yaml
View File

@@ -1,234 +0,0 @@
openapi: 3.0.0
info:
version: 2.0.0
title: Medusa Storefront API
license:
name: MIT
url: https://github.com/medusajs/medusa/blob/master/LICENSE
tags:
- 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: Collections
- name: Currencies
- name: Customers
- name: Payment Collections
description: >
A payment collection is useful for managing additional payments, such as
for Order Edits, or installment payments.
- name: Product Categories
- name: Products
- 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: Shipping Options
servers:
- url: http://localhost:9000
- url: https://api.medusa-commerce.com
paths: {}
components:
responses:
default_error:
description: Default Error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
code: unknown_error
message: An unknown error occurred.
type: unknown_error
invalid_state_error:
description: Invalid State Error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
code: unknown_error
message: The request conflicted with another request. You may retry the request
with the provided Idempotency-Key.
type: QueryRunnerAlreadyReleasedError
invalid_request_error:
description: Invalid Request Error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
code: invalid_request_error
message: Discount with code TEST already exists.
type: duplicate_error
not_found_error:
description: Not Found Error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
example:
message: Entity with id 1 was not found
type: not_found
400_error:
description: Client Error or Multiple Errors
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/Error"
- $ref: "#/components/schemas/MultipleErrors"
examples:
not_allowed:
$ref: "#/components/examples/not_allowed_error"
invalid_data:
$ref: "#/components/examples/invalid_data_error"
MultipleErrors:
$ref: "#/components/examples/multiple_errors"
500_error:
description: Server Error
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
examples:
database:
$ref: "#/components/examples/database_error"
unexpected_state:
$ref: "#/components/examples/unexpected_state_error"
invalid_argument:
$ref: "#/components/examples/invalid_argument_error"
default_error:
$ref: "#/components/examples/default_error"
unauthorized:
description: User is not authorized. Must log in first
content:
text/plain:
schema:
type: string
default: Unauthorized
example: Unauthorized
incorrect_credentials:
description: User does not exist or incorrect credentials
content:
text/plain:
schema:
type: string
default: Unauthorized
example: Unauthorized
examples:
not_allowed_error:
summary: Not Allowed Error
value:
message: Discount must be set to dynamic
type: not_allowed
invalid_data_error:
summary: Invalid Data Error
value:
message: first_name must be a string
type: invalid_data
multiple_errors:
summary: Multiple Errors
value:
message: Provided request body contains errors. Please check the data and retry
the request
errors:
- message: first_name must be a string
type: invalid_data
- message: Discount must be set to dynamic
type: not_allowed
database_error:
summary: Database Error
value:
code: api_error
message: An error occured while hashing password
type: database_error
unexpected_state_error:
summary: Unexpected State Error
value:
message: cart.total must be defined
type: unexpected_state
invalid_argument_error:
summary: Invalid Argument Error
value:
message: cart.total must be defined
type: unexpected_state
default_error:
summary: Default Error
value:
code: unknown_error
message: An unknown error occurred.
type: unknown_error
securitySchemes:
jwt_token:
type: http
x-displayName: JWT Token
scheme: bearer
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.

262
www/utils/generated/oas-output/base/admin.oas.base.yaml
View File

@@ -1,38 +1,14 @@
openapi: 3.0.0
info:
version: 1.0.0
version: 2.0.0
title: Medusa Admin API
license:
name: MIT
url: https://github.com/medusajs/medusa/blob/master/LICENSE
tags:
- name: Apps Oauth
description: >
Some plugins may require to authenticate with third-party services and
store authentication details, such as the authentication token. To do
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.
- name: Auth
description: >
Authentication API Routes allow admin users to manage their session, such
as login or log out.
When an admin user is logged in, the cookie header is set indicating the admin's login session.
externalDocs:
description: How to implement user profiles
url: https://docs.medusajs.com/modules/users/admin/manage-profile
- name: Batch Jobs
description: >
A batch job is a task that is performed by the Medusa backend
asynchronusly. For example, the Import Product feature is implemented
using batch jobs.
Batch Job API Routes allow admins to manage the batch jobs and their state.
externalDocs:
description: How to import products
url: https://docs.medusajs.com/modules/products/admin/import-products
- name: Api Keys
- name: Campaigns
- name: Collections
- name: Currencies
description: >
A store can use unlimited currencies, and each region must be associated
@@ -43,14 +19,6 @@ tags:
description: How to manage currencies
url: https://docs.medusajs.com/modules/regions-and-currencies/admin/manage-currencies
- name: Customer Groups
description: >
Customer Groups can be used to organize customers that share similar data
or attributes into dedicated groups.
This can be useful for different purposes such as setting a different price for a specific customer group.
externalDocs:
description: How to manage customer groups
url: https://docs.medusajs.com/modules/customers/admin/manage-customer-groups
- name: Customers
description: >
Customers can either be created when they register through the Store APIs,
@@ -58,39 +26,11 @@ tags:
externalDocs:
description: How to manage customers
url: https://docs.medusajs.com/modules/customers/admin/manage-customers
- name: Discounts
description: >
Admins can create discounts with conditions and rules, providing them with
advanced settings for variety of cases.
The Discount API Routes can be used to manage discounts, their conditions, resources, and more.
externalDocs:
description: How to manage discounts
url: https://docs.medusajs.com/modules/discounts/admin/manage-discounts
- name: Draft Orders
description: >
A draft order is an order created manually by the admin. It allows admins
to create orders without direct involvement from the customer.
externalDocs:
description: How to manage draft orders
url: https://docs.medusajs.com/modules/orders/admin/manage-draft-orders
- name: Gift Cards
description: >
Admins can create gift cards and send them directly to customers,
specifying options like their balance, region, and more.
These gift cards are different than the saleable gift cards in a store, which are created and managed through Product API Routes.
externalDocs:
description: How to manage gift cards
url: https://docs.medusajs.com/modules/gift-cards/admin/manage-gift-cards#manage-custom-gift-cards
- name: Fulfillment Providers
- name: Fulfillment Sets
- name: Fulfillments
- name: Inventory Items
description: >
Inventory items, provided by the [Inventory
Module](https://docs.medusajs.com/modules/multiwarehouse/inventory-module),
can be used to manage the inventory of saleable items in your store.
externalDocs:
description: How to manage inventory items
url: https://docs.medusajs.com/modules/multiwarehouse/admin/manage-inventory-items
- name: Invites
description: >
An admin can invite new users to manage their team. This would allow new
@@ -98,104 +38,16 @@ tags:
externalDocs:
description: How to manage invites
url: https://docs.medusajs.com/modules/users/admin/manage-invites
- name: Notes
description: >
Notes are created by admins and can be associated with any resource. For
example, an admin can add a note to an order for additional details or
remarks.
- name: Notifications
description: >
Notifications are sent to customers to inform them of new updates. For
example, a notification can be sent to the customer when their order is
place or its state is updated.
The notification's type, such as an email or SMS, is determined by the notification provider installed on the Medusa backend.
- name: Order Edits
description: >
An admin can edit an order to remove, add, or update an item's quantity.
When an admin edits an order, they're stored as an `OrderEdit`.
externalDocs:
description: How to edit an order
url: https://docs.medusajs.com/modules/orders/admin/edit-order
- name: Orders
description: >
Orders are purchases made by customers, typically through a storefront
using the Store API. Draft orders created by the admin are also
transformed to an Order once the payment is captured.
Managing orders include managing fulfillment, payment, claims, reservations, and more.
externalDocs:
description: How to manage orders
url: https://docs.medusajs.com/modules/orders/admin/manage-orders
- name: Payment Collections
description: >
A payment collection is useful for managing additional payments, such as
for Order Edits, or installment payments.
- name: Payments
description: >
A payment can be related to an order, swap, return, or more. It can be
captured or refunded.
- name: Price Lists
description: >
A price list are special prices applied to products based on a set of
conditions, such as customer group.
externalDocs:
description: How to manage price lists
url: https://docs.medusajs.com/modules/price-lists/admin/manage-price-lists
- name: Pricing
- name: Product Categories
description: >
Products can be categoriezed into categories. A product can be added into
more than one category.
externalDocs:
description: How to manage product categories
url: https://docs.medusajs.com/modules/products/admin/manage-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.
- name: Product Tags
description: >
Product tags are string values created when you create or update a product
with a new tag.
Products can have more than one tag, and products can share tags. This allows admins to associate products to similar tags that can be used to filter products.
- name: Product Types
description: >
Product types are string values created when you create or update a
product with a new type.
Products can have one type, and products can share types. This allows admins to associate products with a type that can be used to filter 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.
Product variants can be managed through the Products API Routes.
externalDocs:
description: How to manage product variants
url: https://docs.medusajs.com/modules/products/admin/manage-products#manage-product-variants
- name: Products
description: >
Products are saleable items in a store. This also includes [saleable gift
cards](https://docs.medusajs.com/modules/gift-cards/admin/manage-gift-cards#manage-gift-card-product)
in a store.
externalDocs:
description: How to manage products
url: https://docs.medusajs.com/modules/products/admin/manage-products
- name: Publishable API Keys
description: >
Publishable API Keys can be used to scope Store API calls with an API key,
determining what resources are retrieved when querying the API.
For example, a publishable API key can be associated with one or more sales channels. When it is passed in the header of a request to the List Product store API Route,
the sales channels are inferred from the key and only products associated with those sales channels are retrieved.
Admins can manage publishable API keys and their associated resources. Currently, only Sales Channels are supported as a resource.
externalDocs:
description: How to manage publishable API keys
url: https://docs.medusajs.com/development/publishable-api-keys/admin/manage-publishable-api-keys
- name: Promotions
x-associatedSchema:
$ref: "#/components/schemas/Promotion"
- name: Regions
description: >
Regions are different countries or geographical regions that the commerce
@@ -206,34 +58,6 @@ tags:
description: How to manage regions
url: https://docs.medusajs.com/modules/regions-and-currencies/admin/manage-regions
- name: Reservations
description: >
Reservations, provided by the [Inventory
Module](https://docs.medusajs.com/modules/multiwarehouse/inventory-module),
are quantities of an item that are reserved, typically when an order is
placed but not yet fulfilled.
Reservations can be associated with any resources, but commonly with line items of an order.
externalDocs:
description: How to manage item allocations in orders
url: https://docs.medusajs.com/modules/multiwarehouse/admin/manage-item-allocations-in-orders
- name: Return Reasons
description: >
Return reasons are key-value pairs that are used to specify why an order
return is being created.
Admins can manage available return reasons, and they can be used by both admins and customers when creating a return.
externalDocs:
description: How to manage return reasons
url: https://docs.medusajs.com/modules/orders/admin/manage-returns#manage-return-reasons
- name: Returns
description: >
A return can be created by a customer or an admin to return items in an
order.
Admins can manage these returns and change their state.
externalDocs:
description: How to manage returns
url: https://docs.medusajs.com/modules/orders/admin/manage-returns
- name: Sales Channels
description: >
A sales channel indicates a channel where products can be sold in. For
@@ -244,72 +68,14 @@ tags:
description: How to manage sales channels
url: https://docs.medusajs.com/modules/sales-channels/admin/manage
- name: Shipping Options
description: >
A shipping option is used to define the available shipping methods during
checkout or when creating a return.
Admins can create an unlimited number of shipping options, each associated with a shipping profile and fulfillment provider, among other resources.
externalDocs:
description: Shipping Option architecture
url: https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-option
- name: Shipping Profiles
description: >
A shipping profile is used to group products that can be shipped in the
same manner.
They are created by the admin and they're not associated with a fulfillment provider.
externalDocs:
description: Shipping Profile architecture
url: https://docs.medusajs.com/modules/carts-and-checkout/shipping#shipping-profile
- name: Stock Locations
description: >
A stock location, provided by the [Stock Location
module](https://docs.medusajs.com/modules/multiwarehouse/stock-location-module),
indicates a physical address that stock-kept items, such as physical
products, can be stored in.
An admin can create and manage available stock locations.
externalDocs:
description: How to manage stock locations.
url: https://docs.medusajs.com/modules/multiwarehouse/admin/manage-stock-locations
- name: Store
description: >
A store indicates the general configurations and details about the
commerce store. By default, there's only one store in the Medusa backend.
Admins can manage the store and its details or configurations.
- 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 manage swaps
url: https://docs.medusajs.com/modules/orders/admin/manage-swaps
- name: Stores
- name: Tax Rates
description: >
Each region has at least a default tax rate. Admins can create and manage
additional tax rates that can be applied for certain conditions, such as
for specific product types.
externalDocs:
description: How to manage tax rates
url: https://docs.medusajs.com/modules/taxes/admin/manage-tax-rates
- name: Tax Regions
- name: Uploads
description: >
The upload API Routes are used to upload any type of resources. For
example, they can be used to upload CSV files that are used to import
products into the store.
externalDocs:
description: How to upload CSV file when importing a product.
url: https://docs.medusajs.com/modules/products/admin/import-products#1-upload-csv-file
- name: Users
description: >
A store can have more than one user, each having the same privileges.
Admins can manage users, their passwords, and more.
externalDocs:
description: How to manage users
url: https://docs.medusajs.com/modules/users/admin/manage-users
- name: Workflows Executions
servers:
- url: http://localhost:9000
- url: https://api.medusa-commerce.com

197
www/utils/generated/oas-output/base/store.oas.base.yaml
View File

@@ -1,117 +1,43 @@
openapi: 3.0.0
info:
version: 1.0.0
version: 2.0.0
title: Medusa Storefront API
license:
name: MIT
url: https://github.com/medusajs/medusa/blob/master/LICENSE
tags:
- name: Auth
description: |
Authentication API Routes allow you to manage a customer's session, such as login or log out.
You can send authenticated requests for a customer either using the Cookie header or using the JWT Token.
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.
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: Collections
- name: Currencies
- 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 API Routes allow retrieving a gift card's details by its code. A gift card can be applied to a cart using the Carts API Routes.
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 API Routes. The Orders API Routes 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 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
- 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.
description: >
A payment collection is useful for managing additional payments, such as
for Order Edits, or installment payments.
- name: Product Categories
description: |
Products can be categoriezed into categories. A product can be associated more than one category.
Using these API Routes, 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 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.
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: Products
- name: Regions
description: |
Regions are different countries or geographical regions that the commerce store serves customers in.
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: http://localhost:9000
- url: https://api.medusa-commerce.com
paths: { }
paths: {}
components:
responses:
default_error:
@@ -121,9 +47,9 @@ components:
schema:
$ref: "#/components/schemas/Error"
example:
code: "unknown_error"
message: "An unknown error occurred."
type: "unknown_error"
code: unknown_error
message: An unknown error occurred.
type: unknown_error
invalid_state_error:
description: Invalid State Error
content:
@@ -131,9 +57,10 @@ components:
schema:
$ref: "#/components/schemas/Error"
example:
code: "unknown_error"
message: "The request conflicted with another request. You may retry the request with the provided Idempotency-Key."
type: "QueryRunnerAlreadyReleasedError"
code: unknown_error
message: The request conflicted with another request. You may retry the request
with the provided Idempotency-Key.
type: QueryRunnerAlreadyReleasedError
invalid_request_error:
description: Invalid Request Error
content:
@@ -141,9 +68,9 @@ components:
schema:
$ref: "#/components/schemas/Error"
example:
code: "invalid_request_error"
message: "Discount with code TEST already exists."
type: "duplicate_error"
code: invalid_request_error
message: Discount with code TEST already exists.
type: duplicate_error
not_found_error:
description: Not Found Error
content:
@@ -151,8 +78,8 @@ components:
schema:
$ref: "#/components/schemas/Error"
example:
message: "Entity with id 1 was not found"
type: "not_found"
message: Entity with id 1 was not found
type: not_found
400_error:
description: Client Error or Multiple Errors
content:
@@ -184,7 +111,7 @@ components:
default_error:
$ref: "#/components/examples/default_error"
unauthorized:
description: 'User is not authorized. Must log in first'
description: User is not authorized. Must log in first
content:
text/plain:
schema:
@@ -192,7 +119,7 @@ components:
default: Unauthorized
example: Unauthorized
incorrect_credentials:
description: 'User does not exist or incorrect credentials'
description: User does not exist or incorrect credentials
content:
text/plain:
schema:
@@ -203,44 +130,45 @@ components:
not_allowed_error:
summary: Not Allowed Error
value:
message: "Discount must be set to dynamic"
type: "not_allowed"
message: Discount must be set to dynamic
type: not_allowed
invalid_data_error:
summary: Invalid Data Error
value:
message: "first_name must be a string"
type: "invalid_data"
message: first_name must be a string
type: invalid_data
multiple_errors:
summary: Multiple Errors
value:
message: "Provided request body contains errors. Please check the data and retry the request"
message: Provided request body contains errors. Please check the data and retry
the request
errors:
- message: "first_name must be a string"
type: "invalid_data"
- message: "Discount must be set to dynamic"
type: "not_allowed"
- message: first_name must be a string
type: invalid_data
- message: Discount must be set to dynamic
type: not_allowed
database_error:
summary: Database Error
value:
code: "api_error"
message: "An error occured while hashing password"
type: "database_error"
code: api_error
message: An error occured while hashing password
type: database_error
unexpected_state_error:
summary: Unexpected State Error
value:
message: "cart.total must be defined"
type: "unexpected_state"
message: cart.total must be defined
type: unexpected_state
invalid_argument_error:
summary: Invalid Argument Error
value:
message: "cart.total must be defined"
type: "unexpected_state"
message: cart.total must be defined
type: unexpected_state
default_error:
summary: Default Error
value:
code: "unknown_error"
message: "An unknown error occurred."
type: "unknown_error"
code: unknown_error
message: An unknown error occurred.
type: unknown_error
securitySchemes:
jwt_token:
type: http
@@ -251,37 +179,56 @@ components:
x-displayName: Cookie Session ID
in: cookie
name: connect.sid
description: |
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.
Where `{sid}` is the value of `connect.sid` that you copied.