From 8b2429d24f3eb8d65f0185fa7a23cc02523921b7 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 13 May 2024 17:01:38 +0300 Subject: [PATCH] chore(medusa-oas-cli,oas-github-ci): remove v2 option + generate v2 by default (#7304) * chore(medusa-oas-cli,oas-github-ci): remove v2 option + generate v2 by default * fixes to changeset * fix public url path --- .changeset/cold-bikes-build.md | 9 + .changeset/seven-suits-dream.md | 5 + .../workflows/generate-public-references.yml | 52 +--- package.json | 4 +- .../cli/oas/medusa-oas-cli/src/command-oas.ts | 39 +-- .../oas-github-ci/scripts/build-openapi.js | 7 +- .../oas-output/base-v2/admin.oas.base.yaml | 228 --------------- .../oas-output/base-v2/store.oas.base.yaml | 234 ---------------- .../oas-output/base/admin.oas.base.yaml | 262 +----------------- .../oas-output/base/store.oas.base.yaml | 197 +++++-------- 10 files changed, 111 insertions(+), 926 deletions(-) create mode 100644 .changeset/cold-bikes-build.md create mode 100644 .changeset/seven-suits-dream.md delete mode 100644 www/utils/generated/oas-output/base-v2/admin.oas.base.yaml delete mode 100644 www/utils/generated/oas-output/base-v2/store.oas.base.yaml diff --git a/.changeset/cold-bikes-build.md b/.changeset/cold-bikes-build.md new file mode 100644 index 0000000000..f032b93ff4 --- /dev/null +++ b/.changeset/cold-bikes-build.md @@ -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. \ No newline at end of file diff --git a/.changeset/seven-suits-dream.md b/.changeset/seven-suits-dream.md new file mode 100644 index 0000000000..48ab1537e2 --- /dev/null +++ b/.changeset/seven-suits-dream.md @@ -0,0 +1,5 @@ +--- +"@medusajs/oas-github-ci": patch +--- + +chore(oas-github-ci): remove v2 option diff --git a/.github/workflows/generate-public-references.yml b/.github/workflows/generate-public-references.yml index a4bd50071e..9e3138d22c 100644 --- a/.github/workflows/generate-public-references.yml +++ b/.github/workflows/generate-public-references.yml @@ -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 diff --git a/package.json b/package.json index 49b493e98e..464d5b340f 100644 --- a/package.json +++ b/package.json @@ -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", diff --git a/packages/cli/oas/medusa-oas-cli/src/command-oas.ts b/packages/cli/oas/medusa-oas-cli/src/command-oas.ts index a01a3b13a5..57d90eee9f 100644 --- a/packages/cli/oas/medusa-oas-cli/src/command-oas.ts +++ b/packages/cli/oas/medusa-oas-cli/src/command-oas.ts @@ -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 { /** * 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 } diff --git a/packages/cli/oas/oas-github-ci/scripts/build-openapi.js b/packages/cli/oas/oas-github-ci/scripts/build-openapi.js index b938981153..1fdb092a88 100755 --- a/packages/cli/oas/oas-github-ci/scripts/build-openapi.js +++ b/packages/cli/oas/oas-github-ci/scripts/build-openapi.js @@ -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, diff --git a/www/utils/generated/oas-output/base-v2/admin.oas.base.yaml b/www/utils/generated/oas-output/base-v2/admin.oas.base.yaml deleted file mode 100644 index 68d7567657..0000000000 --- a/www/utils/generated/oas-output/base-v2/admin.oas.base.yaml +++ /dev/null @@ -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 diff --git a/www/utils/generated/oas-output/base-v2/store.oas.base.yaml b/www/utils/generated/oas-output/base-v2/store.oas.base.yaml deleted file mode 100644 index 3855fd5651..0000000000 --- a/www/utils/generated/oas-output/base-v2/store.oas.base.yaml +++ /dev/null @@ -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. diff --git a/www/utils/generated/oas-output/base/admin.oas.base.yaml b/www/utils/generated/oas-output/base/admin.oas.base.yaml index 27870b55e5..68d7567657 100644 --- a/www/utils/generated/oas-output/base/admin.oas.base.yaml +++ b/www/utils/generated/oas-output/base/admin.oas.base.yaml @@ -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 diff --git a/www/utils/generated/oas-output/base/store.oas.base.yaml b/www/utils/generated/oas-output/base/store.oas.base.yaml index fa2ab873f3..3855fd5651 100644 --- a/www/utils/generated/oas-output/base/store.oas.base.yaml +++ b/www/utils/generated/oas-output/base/store.oas.base.yaml @@ -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. \ No newline at end of file + + + Where `{sid}` is the value of `connect.sid` that you copied.