feat(oas): declare x-codegen on Store routes #3074

patrick-medusajs · 2023-01-19T21:18:55Z

What

Declare x-codegen in OAS for Store routes.

Why

We are introducing a new x-codegen OpenApi extension, also known as vendor extension, in order to help with passing information down to code generators.

In our case, we wish to declare the method name that we would expect to call on a client. This mimics our current JS client package.
E.g. medusaClient.product.list where product is the tag of the route and list is the x-codegen.method value.

We are also defining the name of a potential typed object for query parameters. OAS 3.0 does not allow to bundle query parameters under a single definition but it is not uncommon to see API clients handle all query parameters as a single typed object, like our JS client package. With x-codegen.queryParams, a code generator can create a named and typed object to bundle all query parameters for a given route.
E.g. medusaClient.customer.retrieve(id: string, queryParams: AdminGetCustomerParams)

How

Declare x-codegen as an object with fields method and queryParams on all paths.

Match method and queryParams values with equivalent ones from our current JS client package.

Test

Ran OAS validator.
Ran docs build script.

Expect no visible changes to the documentation.

changeset-bot · 2023-01-19T21:18:58Z

⚠️ No Changeset found

Latest commit: be0f3f8

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

patrick-medusajs

self-review: highlighted noteworthy code changes.
Added links to JS client.

patrick-medusajs · 2023-01-19T21:24:35Z

packages/medusa/src/api/routes/store/auth/create-session.ts

+ *       schema:
+ *         $ref: "#/components/schemas/StorePostAuthReq"
+ * x-codegen:
+ *   method: authenticate


medusa/packages/medusa-js/src/resources/auth.ts

Line 16 in 5523222

authenticate(payload: StorePostAuthReq, customHeaders: Record<string, any> = {}): ResponsePromise<StoreAuthRes> {

patrick-medusajs · 2023-01-19T21:25:01Z

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

@@ -4,6 +4,8 @@
 * summary: "Customer Log out"
 * description: "Destroys a Customer's authenticated session."
 * x-authenticated: true
+ * x-codegen:
+ *   method: deleteSession


medusa/packages/medusa-js/src/resources/auth.ts

Line 25 in 5523222

deleteSession(customHeaders: Record<string, any> = {}): ResponsePromise<void> {

patrick-medusajs · 2023-01-19T21:25:19Z

packages/medusa/src/api/routes/store/auth/exists.ts

@@ -13,6 +13,8 @@ import CustomerService from "../../../../services/customer"
 *       format: email
 *     required: true
 *     description: The email to check if exists.
+ * x-codegen:
+ *   method: exists


medusa/packages/medusa-js/src/resources/auth.ts

Line 47 in 5523222

exists(email: string, customHeaders: Record<string, any> = {}): ResponsePromise<StoreGetAuthEmailRes> {

patrick-medusajs · 2023-01-19T21:25:30Z

packages/medusa/src/api/routes/store/auth/get-session.ts

@@ -6,6 +6,8 @@ import CustomerService from "../../../../services/customer"
 * summary: "Get Current Customer"
 * description: "Gets the currently logged in Customer."
 * x-authenticated: true
+ * x-codegen:
+ *   method: getSession


medusa/packages/medusa-js/src/resources/auth.ts

Line 36 in 5523222

getSession(customHeaders: Record<string, any> = {}): ResponsePromise<StoreAuthRes> {

patrick-medusajs · 2023-01-19T21:26:35Z

packages/medusa/src/api/routes/store/carts/add-shipping-method.ts

+ *       schema:
+ *         $ref: "#/components/schemas/StorePostCartsCartShippingMethodReq"
+ * x-codegen:
+ *   method: addShippingMethod


medusa/packages/medusa-js/src/resources/carts.ts

Lines 24 to 28 in 5523222

addShippingMethod(

cart_id: string,

payload: StorePostCartsCartShippingMethodReq,

customHeaders: Record<string, any> = {}

): ResponsePromise<StoreCartsRes> {

patrick-medusajs · 2023-01-19T21:56:23Z

packages/medusa/src/api/routes/store/shipping-options/list-shipping-options.ts

@@ -8,6 +8,8 @@ import ShippingProfileService from "../../../../services/shipping-profile"
 * description: "Retrieves a list of Shipping Options available to a cart."
 * parameters:
 *   - (path) cart_id {string} The id of the Cart.
+ * x-codegen:
+ *   method: listCartOptions


medusa/packages/medusa-js/src/resources/shipping-options.ts

Line 16 in 5523222

listCartOptions(cart_id: string, customHeaders: Record<string, any> = {}): ResponsePromise<StoreShippingOptionsListRes> {

patrick-medusajs · 2023-01-19T21:56:43Z

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

@@ -28,6 +28,8 @@ import { validator } from "../../../../utils/validator"
 *     application/json:
 *       schema:
 *         $ref: "#/components/schemas/StorePostSwapsReq"
+ * x-codegen:
+ *   method: create


medusa/packages/medusa-js/src/resources/swaps.ts

Line 12 in 5523222

create(payload: StorePostSwapsReq, customHeaders: Record<string, any> = {}): ResponsePromise<StoreSwapsRes> {

patrick-medusajs · 2023-01-19T21:56:55Z

packages/medusa/src/api/routes/store/swaps/get-swap-by-cart.ts

@@ -7,6 +7,8 @@ import SwapService from "../../../../services/swap"
 * description: "Retrieves a Swap by the id of the Cart used to confirm the Swap."
 * parameters:
 *   - (path) cart_id {string} The id of the Cart
+ * x-codegen:
+ *   method: retrieveByCartId


medusa/packages/medusa-js/src/resources/swaps.ts

Line 23 in 5523222

retrieveByCartId(cart_id: string, customHeaders: Record<string, any> = {}): ResponsePromise<StoreSwapsRes> {

patrick-medusajs · 2023-01-19T22:01:24Z

packages/medusa/src/api/routes/store/variants/get-variant.ts

+ *   method: retrieve
+ *   queryParams: StoreGetVariantsVariantParams


Breaking change. client.productVariants.retrieve instead of client.products.variants.retrieve

medusa/packages/medusa-js/src/resources/product-variants.ts

Lines 17 to 20 in 5523222

retrieve(id: string, customHeaders: Record<string, any> = {}): ResponsePromise<StoreVariantsRes> {

const path = `/store/variants/${id}`

return this.client.request("GET", path, undefined, {}, customHeaders)

}

patrick-medusajs · 2023-01-19T22:03:55Z

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

+ *   method: list
+ *   queryParams: StoreGetVariantsParams


medusa/packages/medusa-js/src/resources/product-variants.ts

Lines 17 to 20 in 5523222

retrieve(id: string, customHeaders: Record<string, any> = {}): ResponsePromise<StoreVariantsRes> {

const path = `/store/variants/${id}`

return this.client.request("GET", path, undefined, {}, customHeaders)

}

pKorsholm

LGTM! Very nice!

Given the breaking changes are not breaking the current medusa-js client, but will break in the future I think it's acceptable, also some of the proposed routes make more sense imo 😅

olivermrbl

LGTM! 💪

shahednasser

Just a small change 🙂

shahednasser · 2023-01-23T09:00:21Z

packages/medusa/src/api/routes/store/carts/set-payment-session.ts

@@ -13,6 +13,13 @@ import { validator } from "../../../../utils/validator"
 * parameters:
 *   - (path) id=* {string} The ID of the Cart.
 *   - (body) provider_id=* {string} The ID of the Payment Provider.


This should be removed

Good catch! Fixed in afe7924

shahednasser

LGTM

patrick-medusajs self-assigned this Jan 19, 2023

feat(oas): declare x-codegen on Store routes

5523222

patrick-medusajs force-pushed the feat/oas-x-codegen-store branch from a511e6e to 5523222 Compare January 19, 2023 21:23

patrick-medusajs added 3 commits January 19, 2023 16:51

fixup! feat(oas): declare x-codegen on Store routes

98a7fa6

fixup! feat(oas): declare x-codegen on Store routes

b307b92

fixup! feat(oas): declare x-codegen on Store routes

1b5badd

patrick-medusajs commented Jan 19, 2023

View reviewed changes

patrick-medusajs marked this pull request as ready for review January 19, 2023 22:07

patrick-medusajs requested a review from a team as a code owner January 19, 2023 22:07

pKorsholm approved these changes Jan 20, 2023

View reviewed changes

patrick-medusajs requested review from shahednasser and a team January 20, 2023 18:34

olivermrbl approved these changes Jan 21, 2023

View reviewed changes

shahednasser requested changes Jan 23, 2023

View reviewed changes

patrick-medusajs and others added 2 commits January 23, 2023 10:14

fix(oas): remove provider_id (body) parameters

afe7924

Merge branch 'develop' into feat/oas-x-codegen-store

be0f3f8

patrick-medusajs added the automerge label Jan 23, 2023

patrick-medusajs requested a review from shahednasser January 23, 2023 15:15

shahednasser approved these changes Jan 23, 2023

View reviewed changes

kodiakhq bot merged commit 6e89d94 into develop Jan 23, 2023

kodiakhq bot deleted the feat/oas-x-codegen-store branch January 23, 2023 15:47

patrick-medusajs mentioned this pull request Jan 30, 2023

feat(medusa): batch remove products from a category #3141

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(oas): declare x-codegen on Store routes #3074

feat(oas): declare x-codegen on Store routes #3074

patrick-medusajs commented Jan 19, 2023

changeset-bot bot commented Jan 19, 2023 •

edited

patrick-medusajs left a comment

patrick-medusajs Jan 19, 2023

patrick-medusajs Jan 19, 2023

patrick-medusajs Jan 19, 2023

patrick-medusajs Jan 19, 2023

patrick-medusajs Jan 19, 2023

patrick-medusajs Jan 19, 2023

patrick-medusajs Jan 19, 2023

patrick-medusajs Jan 19, 2023

patrick-medusajs Jan 19, 2023

patrick-medusajs Jan 19, 2023

pKorsholm left a comment

olivermrbl left a comment

shahednasser left a comment

shahednasser Jan 23, 2023

patrick-medusajs Jan 23, 2023

shahednasser left a comment

	addShippingMethod(
	cart_id: string,
	payload: StorePostCartsCartShippingMethodReq,
	customHeaders: Record<string, any> = {}
	): ResponsePromise<StoreCartsRes> {

		* method: retrieve
		* queryParams: StoreGetVariantsVariantParams

	retrieve(id: string, customHeaders: Record<string, any> = {}): ResponsePromise<StoreVariantsRes> {
	const path = `/store/variants/${id}`
	return this.client.request("GET", path, undefined, {}, customHeaders)
	}

feat(oas): declare x-codegen on Store routes #3074

feat(oas): declare x-codegen on Store routes #3074

Conversation

patrick-medusajs commented Jan 19, 2023

What

Why

How

Test

changeset-bot bot commented Jan 19, 2023 • edited

⚠️ No Changeset found

patrick-medusajs left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pKorsholm left a comment

Choose a reason for hiding this comment

olivermrbl left a comment

Choose a reason for hiding this comment

shahednasser left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shahednasser left a comment

Choose a reason for hiding this comment

changeset-bot bot commented Jan 19, 2023 •

edited