chore(oas): replace requestBody with $ref to req class JSDoc OAS (#2867)

### What

Move inline OAS requestBody schema declaration under their respective class-validator classes in order to expose them through  `#/components/schemas`. Replace inline OAS requestBody schema with a `$ref` reference pointing to the newly declared schema.

### Why

Having requestBody declared as its own "named" schema will allow OAS code generators to output typed entities/DTO that can be manipulate without having to reference the route/operation.

### How

Declare a new @schema JSDoc for each class-validator used to parse and validate request body. Move the current inline requestBody to the new @schema.

### Test

- Ran OAS validator.
- Ran docs build script.

Expect no visible changes to the documentation.

### Out-of-scope

requestBody of type `multipart/form-data` used for file uploads. These will be address as part of CORE-934
- [create-upload.ts](https://github.com/medusajs/medusa/blob/58d23a7b45b6dde8bdeed0bb268139a0017f1649/packages/medusa/src/api/routes/admin/uploads/create-upload.ts#L87-L90)
- [create-protected-upload.ts](https://github.com/medusajs/medusa/blob/58d23a7b45b6dde8bdeed0bb268139a0017f1649/packages/medusa/src/api/routes/admin/uploads/create-protected-upload.ts#L87-L90)

Path Parameter and Query Parameter. These will need more research and experimentation, part of CORE-931

---

Resolves CORE-853

.changeset/rich-laws-guess.md

@@ -0,0 +1,5 @@
+---
+"@medusajs/medusa": patch
+---
+
+chore(oas): replace requestBody with $ref to req class JSDoc OAS

packages/medusa/src/api/routes/admin/apps/authorize-app.ts

@@ -13,21 +13,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostAppsReq"
- *         required:
- *           - application_name
- *           - state
- *           - code
- *         properties:
- *           application_name:
- *             type: string
- *             description:  Name of the application for the token to be generated for.
- *           state:
- *             type: string
- *             description: State of the application.
- *           code:
- *             type: string
- *             description: The code for the generated token.
  * x-codeSamples:
  *   - lang: Shell
  *     label: cURL
@@ -79,6 +65,24 @@ export default async (req, res) => {
   res.status(200).json({ apps: data })
 }
 
+/**
+ * @schema AdminPostAppsReq
+ * type: object
+ * required:
+ *   - application_name
+ *   - state
+ *   - code
+ * properties:
+ *   application_name:
+ *     type: string
+ *     description:  Name of the application for the token to be generated for.
+ *   state:
+ *     type: string
+ *     description: State of the application.
+ *   code:
+ *     type: string
+ *     description: The code for the generated token.
+ */
 export class AdminPostAppsReq {
   @IsString()
   @IsNotEmpty()

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

@@ -20,19 +20,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostAuthReq"
- *         required:
- *           - email
- *           - password
- *         properties:
- *           email:
- *             type: string
- *             description: The User's email.
- *             format: email
- *           password:
- *             type: string
- *             description: The User's password.
- *             format: password
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -113,6 +101,22 @@ export default async (req, res) => {
   }
 }
 
+/**
+ * @schema AdminPostAuthReq
+ * type: object
+ * required:
+ *   - email
+ *   - password
+ * properties:
+ *   email:
+ *     type: string
+ *     description: The User's email.
+ *     format: email
+ *   password:
+ *     type: string
+ *     description: The User's password.
+ *     format: password
+ */
 export class AdminPostAuthReq {
   @IsEmail()
   @IsNotEmpty()

packages/medusa/src/api/routes/admin/batch/create-batch-job.ts

@@ -15,38 +15,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *    application/json:
  *      schema:
- *        type: object
+ *        $ref: "#/components/schemas/AdminPostBatchesReq"
- *        required:
- *          - type
- *          - context
- *        properties:
- *          type:
- *            type: string
- *            description: The type of batch job to start.
- *            example: product-export
- *          context:
- *            type: object
- *            description: Additional infomration regarding the batch to be used for processing.
- *            example:
- *              shape:
- *                prices:
- *                  - region: null
- *                    currency_code: "eur"
- *                dynamicImageColumnCount: 4
- *                dynamicOptionColumnCount: 2
- *              list_config:
- *                skip: 0
- *                take: 50
- *                order:
- *                  created_at: "DESC"
- *                relations:
- *                  - variants
- *                  - variant.prices
- *                  - images
- *          dry_run:
- *            type: boolean
- *            description: Set a batch job in dry_run mode to get some information on what will be done without applying any modifications.
- *            default: false
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -120,6 +89,41 @@ export default async (req, res) => {
   res.status(201).json({ batch_job })
 }
 
+/**
+ * @schema AdminPostBatchesReq
+ * type: object
+ * required:
+ *   - type
+ *   - context
+ * properties:
+ *   type:
+ *     type: string
+ *     description: The type of batch job to start.
+ *     example: product-export
+ *   context:
+ *     type: object
+ *     description: Additional infomration regarding the batch to be used for processing.
+ *     example:
+ *       shape:
+ *         prices:
+ *           - region: null
+ *             currency_code: "eur"
+ *         dynamicImageColumnCount: 4
+ *         dynamicOptionColumnCount: 2
+ *       list_config:
+ *         skip: 0
+ *         take: 50
+ *         order:
+ *           created_at: "DESC"
+ *         relations:
+ *           - variants
+ *           - variant.prices
+ *           - images
+ *   dry_run:
+ *     type: boolean
+ *     description: Set a batch job in dry_run mode to get some information on what will be done without applying any modifications.
+ *     default: false
+ */
 export class AdminPostBatchesReq {
   @IsString()
   type: string

packages/medusa/src/api/routes/admin/collections/add-products.ts

@@ -16,16 +16,7 @@ import ProductCollectionService from "../../../../services/product-collection"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostProductsToCollectionReq"
- *         required:
- *           - product_ids
- *         properties:
- *           product_ids:
- *             description: "An array of Product IDs to add to the Product Collection."
- *             type: array
- *             items:
- *               description: "The ID of a Product to add to the Product Collection."
- *               type: string
  * x-codeSamples:
  *   - lang: Shell
  *     label: cURL
@@ -86,6 +77,19 @@ export default async (req: Request, res: Response) => {
   res.status(200).json({ collection })
 }
 
+/**
+ * @schema AdminPostProductsToCollectionReq
+ * type: object
+ * required:
+ *   - product_ids
+ * properties:
+ *   product_ids:
+ *     description: "An array of Product IDs to add to the Product Collection."
+ *     type: array
+ *     items:
+ *       description: "The ID of a Product to add to the Product Collection."
+ *       type: string
+ */
 export class AdminPostProductsToCollectionReq {
   @ArrayNotEmpty()
   @IsString({ each: true })

packages/medusa/src/api/routes/admin/collections/create-collection.ts

@@ -13,19 +13,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostCollectionsReq"
- *         required:
- *           - title
- *         properties:
- *           title:
- *             type: string
- *             description:  The title to identify the Collection by.
- *           handle:
- *             type: string
- *             description:  An optional handle to be used in slugs, if none is provided we will kebab-case the title.
- *           metadata:
- *             description: An optional set of key-value pairs to hold additional information.
- *             type: object
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -95,6 +83,22 @@ export default async (req: Request, res: Response) => {
   res.status(200).json({ collection })
 }
 
+/**
+ * @schema AdminPostCollectionsReq
+ * type: object
+ * required:
+ *   - title
+ * properties:
+ *   title:
+ *     type: string
+ *     description:  The title to identify the Collection by.
+ *   handle:
+ *     type: string
+ *     description:  An optional handle to be used in slugs, if none is provided we will kebab-case the title.
+ *   metadata:
+ *     description: An optional set of key-value pairs to hold additional information.
+ *     type: object
+ */
 export class AdminPostCollectionsReq {
   @IsString()
   @IsNotEmpty()

packages/medusa/src/api/routes/admin/collections/remove-products.ts

@@ -16,16 +16,7 @@ import ProductCollectionService from "../../../../services/product-collection"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminDeleteProductsFromCollectionReq"
- *         required:
- *           - product_ids
- *         properties:
- *           product_ids:
- *             description: "An array of Product IDs to remove from the Product Collection."
- *             type: array
- *             items:
- *               description: "The ID of a Product to add to the Product Collection."
- *               type: string
  * x-codeSamples:
  *   - lang: Shell
  *     label: cURL
@@ -101,6 +92,19 @@ export default async (req: Request, res: Response) => {
   })
 }
 
+/**
+ * @schema AdminDeleteProductsFromCollectionReq
+ * type: object
+ * required:
+ *   - product_ids
+ * properties:
+ *   product_ids:
+ *     description: "An array of Product IDs to remove from the Product Collection."
+ *     type: array
+ *     items:
+ *       description: "The ID of a Product to add to the Product Collection."
+ *       type: string
+ */
 export class AdminDeleteProductsFromCollectionReq {
   @ArrayNotEmpty()
   @IsString({ each: true })

packages/medusa/src/api/routes/admin/collections/update-collection.ts

@@ -15,17 +15,7 @@ import ProductCollectionService from "../../../../services/product-collection"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostCollectionsCollectionReq"
- *         properties:
- *           title:
- *             type: string
- *             description:  The title to identify the Collection by.
- *           handle:
- *             type: string
- *             description:  An optional handle to be used in slugs, if none is provided we will kebab-case the title.
- *           metadata:
- *             description: An optional set of key-value pairs to hold additional information.
- *             type: object
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -98,6 +88,20 @@ export default async (req: Request, res: Response) => {
   res.status(200).json({ collection })
 }
 
+/**
+ * @schema AdminPostCollectionsCollectionReq
+ * type: object
+ * properties:
+ *   title:
+ *     type: string
+ *     description:  The title to identify the Collection by.
+ *   handle:
+ *     type: string
+ *     description:  An optional handle to be used in slugs, if none is provided we will kebab-case the title.
+ *   metadata:
+ *     description: An optional set of key-value pairs to hold additional information.
+ *     type: object
+ */
 export class AdminPostCollectionsCollectionReq {
   @IsString()
   @IsOptional()

packages/medusa/src/api/routes/admin/currencies/update-currency.ts

@@ -17,11 +17,7 @@ import TaxInclusivePricingFeatureFlag from "../../../../loaders/feature-flags/ta
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostCurrenciesCurrencyReq"
- *         properties:
- *           includes_tax:
- *             type: boolean
- *             description: "[EXPERIMENTAL] Tax included in prices of currency."
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -67,6 +63,14 @@ export default async (req: ExtendedRequest<Currency>, res) => {
   res.json({ currency })
 }
 
+/**
+ * @schema AdminPostCurrenciesCurrencyReq
+ * type: object
+ * properties:
+ *   includes_tax:
+ *     type: boolean
+ *     description: "[EXPERIMENTAL] Tax included in prices of currency."
+ */
 export class AdminPostCurrenciesCurrencyReq {
   @FeatureFlagDecorators(TaxInclusivePricingFeatureFlag.key, [
     IsOptional(),

packages/medusa/src/api/routes/admin/customer-groups/add-customers-batch.ts

@@ -19,20 +19,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostCustomerGroupsGroupCustomersBatchReq"
- *         required:
- *           - customer_ids
- *         properties:
- *           customer_ids:
- *             description: "The ids of the customers to add"
- *             type: array
- *             items:
- *               required:
- *                 - id
- *               properties:
- *                 id:
- *                   description: ID of the customer
- *                   type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -118,6 +105,23 @@ export default async (req: Request, res: Response) => {
   res.status(200).json({ customer_group })
 }
 
+/**
+ * @schema AdminPostCustomerGroupsGroupCustomersBatchReq
+ * type: object
+ * required:
+ *   - customer_ids
+ * properties:
+ *   customer_ids:
+ *     description: "The ids of the customers to add"
+ *     type: array
+ *     items:
+ *       required:
+ *         - id
+ *       properties:
+ *         id:
+ *           description: ID of the customer
+ *           type: string
+ */
 export class AdminPostCustomerGroupsGroupCustomersBatchReq {
   @ValidateNested({ each: true })
   @Type(() => CustomerGroupsBatchCustomer)

packages/medusa/src/api/routes/admin/customer-groups/delete-customers-batch.ts

@@ -19,20 +19,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminDeleteCustomerGroupsGroupCustomerBatchReq"
- *         required:
- *           - customer_ids
- *         properties:
- *           customer_ids:
- *             description: "The ids of the customers to remove"
- *             type: array
- *             items:
- *               required:
- *                 - id
- *               properties:
- *                 id:
- *                   description: ID of the customer
- *                   type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -118,6 +105,23 @@ export default async (req: Request, res: Response) => {
   res.status(200).json({ customer_group })
 }
 
+/**
+ * @schema AdminDeleteCustomerGroupsGroupCustomerBatchReq
+ * type: object
+ * required:
+ *   - customer_ids
+ * properties:
+ *   customer_ids:
+ *     description: "The ids of the customers to remove"
+ *     type: array
+ *     items:
+ *       required:
+ *         - id
+ *       properties:
+ *         id:
+ *           description: ID of the customer
+ *           type: string
+ */
 export class AdminDeleteCustomerGroupsGroupCustomerBatchReq {
   @ValidateNested({ each: true })
   @Type(() => CustomerGroupsBatchCustomer)

packages/medusa/src/api/routes/admin/customer-groups/update-customer-group.ts

@@ -19,14 +19,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostCustomerGroupsGroupReq"
- *         properties:
- *           name:
- *             description: "Name of the customer group"
- *             type: string
- *           metadata:
- *             description: "Metadata for the customer."
- *             type: object
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -114,6 +107,17 @@ export default async (req: Request, res: Response) => {
   res.json({ customer_group: customerGroup })
 }
 
+/**
+ * @schema AdminPostCustomerGroupsGroupReq
+ * type: object
+ * properties:
+ *   name:
+ *     description: "Name of the customer group"
+ *     type: string
+ *   metadata:
+ *     description: "Metadata for the customer."
+ *     type: object
+ */
 export class AdminPostCustomerGroupsGroupReq {
   @IsString()
   @IsOptional()

packages/medusa/src/api/routes/admin/customers/create-customer.ts

@@ -14,33 +14,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostCustomersReq"
- *         required:
- *           - email
- *           - first_name
- *           - last_name
- *           - password
- *         properties:
- *           email:
- *             type: string
- *             description: The customer's email.
- *             format: email
- *           first_name:
- *             type: string
- *             description: The customer's first name.
- *           last_name:
- *             type: string
- *             description: The customer's last name.
- *           password:
- *             type: string
- *             description: The customer's password.
- *             format: password
- *           phone:
- *             type: string
- *             description: The customer's phone number.
- *           metadata:
- *             description: An optional set of key-value pairs to hold additional information.
- *             type: object
  * tags:
  *   - Customer
  * x-codeSamples:
@@ -110,6 +84,36 @@ export default async (req, res) => {
   res.status(201).json({ customer })
 }
 
+/**
+ * @schema AdminPostCustomersReq
+ * type: object
+ * required:
+ *   - email
+ *   - first_name
+ *   - last_name
+ *   - password
+ * properties:
+ *   email:
+ *     type: string
+ *     description: The customer's email.
+ *     format: email
+ *   first_name:
+ *     type: string
+ *     description: The customer's first name.
+ *   last_name:
+ *     type: string
+ *     description: The customer's last name.
+ *   password:
+ *     type: string
+ *     description: The customer's password.
+ *     format: password
+ *   phone:
+ *     type: string
+ *     description: The customer's phone number.
+ *   metadata:
+ *     description: An optional set of key-value pairs to hold additional information.
+ *     type: object
+ */
 export class AdminPostCustomersReq {
   @IsEmail()
   email: string

packages/medusa/src/api/routes/admin/customers/update-customer.ts

@@ -29,38 +29,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostCustomersCustomerReq"
- *         properties:
- *           email:
- *             type: string
- *             description: The Customer's email.
- *             format: email
- *           first_name:
- *             type: string
- *             description:  The Customer's first name.
- *           last_name:
- *             type: string
- *             description:  The Customer's last name.
- *           phone:
- *             type: string
- *             description: The Customer's phone number.
- *           password:
- *             type: string
- *             description: The Customer's password.
- *             format: password
- *           groups:
- *             type: array
- *             items:
- *               required:
- *                 - id
- *               properties:
- *                 id:
- *                   description: The ID of a customer group
- *                   type: string
- *             description: A list of customer groups to which the customer belongs.
- *           metadata:
- *             description: An optional set of key-value pairs to hold additional information.
- *             type: object
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -156,6 +125,41 @@ class Group {
   id: string
 }
 
+/**
+ * @schema AdminPostCustomersCustomerReq
+ * type: object
+ * properties:
+ *   email:
+ *     type: string
+ *     description: The Customer's email.
+ *     format: email
+ *   first_name:
+ *     type: string
+ *     description:  The Customer's first name.
+ *   last_name:
+ *     type: string
+ *     description:  The Customer's last name.
+ *   phone:
+ *     type: string
+ *     description: The Customer's phone number.
+ *   password:
+ *     type: string
+ *     description: The Customer's password.
+ *     format: password
+ *   groups:
+ *     type: array
+ *     items:
+ *       required:
+ *         - id
+ *       properties:
+ *         id:
+ *           description: The ID of a customer group
+ *           type: string
+ *     description: A list of customer groups to which the customer belongs.
+ *   metadata:
+ *     description: An optional set of key-value pairs to hold additional information.
+ *     type: object
+ */
 export class AdminPostCustomersCustomerReq {
   @IsEmail()
   @IsOptional()

packages/medusa/src/api/routes/admin/discounts/add-resources-to-condition-batch.ts

@@ -24,20 +24,7 @@ import { FindParams } from "../../../../types/common"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostDiscountsDiscountConditionsConditionBatchReq"
- *         required:
- *           - resources
- *         properties:
- *           resources:
- *             description: The resources to be added to the discount condition
- *             type: array
- *             items:
- *               required:
- *                 - id
- *               properties:
- *                 id:
- *                   description: The id of the item
- *                   type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -124,9 +111,27 @@ export default async (req: Request, res: Response) => {
   res.status(200).json({ discount })
 }
 
+/**
+ * @schema AdminPostDiscountsDiscountConditionsConditionBatchReq
+ * type: object
+ * required:
+ *   - resources
+ * properties:
+ *   resources:
+ *     description: The resources to be added to the discount condition
+ *     type: array
+ *     items:
+ *       required:
+ *         - id
+ *       properties:
+ *         id:
+ *           description: The id of the item
+ *           type: string
+ */
 export class AdminPostDiscountsDiscountConditionsConditionBatchReq {
   @IsArray()
   resources: { id: string }[]
 }
 
+// eslint-disable-next-line max-len
 export class AdminPostDiscountsDiscountConditionsConditionBatchParams extends FindParams {}

packages/medusa/src/api/routes/admin/discounts/create-condition.ts

@@ -22,39 +22,7 @@ import { FindParams } from "../../../../types/common"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostDiscountsDiscountConditions"
- *         required:
- *           - operator
- *         properties:
- *           operator:
- *              description: Operator of the condition
- *              type: string
- *              enum: [in, not_in]
- *           products:
- *              type: array
- *              description: list of product IDs if the condition is applied on products.
- *              items:
- *                type: string
- *           product_types:
- *              type: array
- *              description: list of product type IDs if the condition is applied on product types.
- *              items:
- *                type: string
- *           product_collections:
- *              type: array
- *              description: list of product collection IDs if the condition is applied on product collections.
- *              items:
- *                type: string
- *           product_tags:
- *              type: array
- *              description: list of product tag IDs if the condition is applied on product tags.
- *              items:
- *                type: string
- *           customer_groups:
- *              type: array
- *              description: list of customer group IDs if the condition is applied on customer groups.
- *              items:
- *                type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -130,6 +98,42 @@ export default async (req: Request, res: Response) => {
   res.status(200).json({ discount })
 }
 
+/**
+ * @schema AdminPostDiscountsDiscountConditions
+ * type: object
+ * required:
+ *   - operator
+ * properties:
+ *   operator:
+ *      description: Operator of the condition
+ *      type: string
+ *      enum: [in, not_in]
+ *   products:
+ *      type: array
+ *      description: list of product IDs if the condition is applied on products.
+ *      items:
+ *        type: string
+ *   product_types:
+ *      type: array
+ *      description: list of product type IDs if the condition is applied on product types.
+ *      items:
+ *        type: string
+ *   product_collections:
+ *      type: array
+ *      description: list of product collection IDs if the condition is applied on product collections.
+ *      items:
+ *        type: string
+ *   product_tags:
+ *      type: array
+ *      description: list of product tag IDs if the condition is applied on product tags.
+ *      items:
+ *        type: string
+ *   customer_groups:
+ *      type: array
+ *      description: list of customer group IDs if the condition is applied on customer groups.
+ *      items:
+ *        type: string
+ */
 // eslint-disable-next-line max-len
 export class AdminPostDiscountsDiscountConditions extends AdminUpsertConditionsReq {
   @IsString()

packages/medusa/src/api/routes/admin/discounts/create-discount.ts

@@ -38,6 +38,93 @@ import { FindParams } from "../../../../types/common"
  *   content:
  *     application/json:
  *       schema:
+ *         $ref: "#/components/schemas/AdminPostDiscountsReq"
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       import { AllocationType, DiscountRuleType } from "@medusajs/medusa"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.discounts.create({
+ *         code: 'TEST',
+ *         rule: {
+ *           type: DiscountRuleType.FIXED,
+ *           value: 10,
+ *           allocation: AllocationType.ITEM
+ *         },
+ *         regions: ["reg_XXXXXXXX"],
+ *         is_dynamic: false,
+ *         is_disabled: false
+ *       })
+ *       .then(({ discount }) => {
+ *         console.log(discount.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/discounts' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "code": "TEST",
+ *           "rule": {
+ *              "type": "fixed",
+ *              "value": 10,
+ *              "allocation": "item"
+ *           },
+ *           "regions": ["reg_XXXXXXXX"]
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
+ * tags:
+ *   - Discount
+ * responses:
+ *   200:
+ *     description: OK
+ *     content:
+ *       application/json:
+ *         schema:
+ *           type: object
+ *           properties:
+ *             discount:
+ *               $ref: "#/components/schemas/Discount"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
+ */
+
+export default async (req: Request, res: Response) => {
+  const discountService: DiscountService = req.scope.resolve("discountService")
+
+  const manager: EntityManager = req.scope.resolve("manager")
+  const created = await manager.transaction(async (transactionManager) => {
+    return await discountService
+      .withTransaction(transactionManager)
+      .create(req.validatedBody as AdminPostDiscountsReq)
+  })
+
+  const discount = await discountService.retrieve(
+    created.id,
+    req.retrieveConfig
+  )
+
+  res.status(200).json({ discount })
+}
+
+/**
+ * @schema AdminPostDiscountsReq
  * type: object
  * required:
  *   - code
@@ -137,90 +224,7 @@ import { FindParams } from "../../../../types/common"
  *   metadata:
  *     description: An optional set of key-value pairs to hold additional information.
  *     type: object
- * x-codeSamples:
- *   - lang: JavaScript
- *     label: JS Client
- *     source: |
- *       import Medusa from "@medusajs/medusa-js"
- *       import { AllocationType, DiscountRuleType } from "@medusajs/medusa"
- *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
- *       // must be previously logged in or use api token
- *       medusa.admin.discounts.create({
- *         code: 'TEST',
- *         rule: {
- *           type: DiscountRuleType.FIXED,
- *           value: 10,
- *           allocation: AllocationType.ITEM
- *         },
- *         regions: ["reg_XXXXXXXX"],
- *         is_dynamic: false,
- *         is_disabled: false
- *       })
- *       .then(({ discount }) => {
- *         console.log(discount.id);
- *       });
- *   - lang: Shell
- *     label: cURL
- *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/discounts' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
- *       --data-raw '{
- *           "code": "TEST",
- *           "rule": {
- *              "type": "fixed",
- *              "value": 10,
- *              "allocation": "item"
- *           },
- *           "regions": ["reg_XXXXXXXX"]
- *       }'
- * security:
- *   - api_token: []
- *   - cookie_auth: []
- * tags:
- *   - Discount
- * responses:
- *   200:
- *     description: OK
- *     content:
- *       application/json:
- *         schema:
- *           type: object
- *           properties:
- *             discount:
- *               $ref: "#/components/schemas/Discount"
- *   "400":
- *     $ref: "#/components/responses/400_error"
- *   "401":
- *     $ref: "#/components/responses/unauthorized"
- *   "404":
- *     $ref: "#/components/responses/not_found_error"
- *   "409":
- *     $ref: "#/components/responses/invalid_state_error"
- *   "422":
- *     $ref: "#/components/responses/invalid_request_error"
- *   "500":
- *     $ref: "#/components/responses/500_error"
  */
-
-export default async (req: Request, res: Response) => {
-  const discountService: DiscountService = req.scope.resolve("discountService")
-
-  const manager: EntityManager = req.scope.resolve("manager")
-  const created = await manager.transaction(async (transactionManager) => {
-    return await discountService
-      .withTransaction(transactionManager)
-      .create(req.validatedBody as AdminPostDiscountsReq)
-  })
-
-  const discount = await discountService.retrieve(
-    created.id,
-    req.retrieveConfig
-  )
-
-  res.status(200).json({ discount })
-}
-
 export class AdminPostDiscountsReq {
   @IsString()
   @IsNotEmpty()

packages/medusa/src/api/routes/admin/discounts/delete-resources-from-condition-batch.ts

@@ -23,20 +23,7 @@ import { FindParams } from "../../../../types/common"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminDeleteDiscountsDiscountConditionsConditionBatchReq"
- *         required:
- *           - resources
- *         properties:
- *           resources:
- *             description: The resources to be deleted from the discount condition
- *             type: array
- *             items:
- *               required:
- *                 - id
- *               properties:
- *                 id:
- *                   description: The id of the item
- *                   type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -123,8 +110,26 @@ export default async (req: Request, res: Response) => {
   res.status(200).json({ discount })
 }
 
+// eslint-disable-next-line max-len
 export class AdminDeleteDiscountsDiscountConditionsConditionBatchParams extends FindParams {}
 
+/**
+ * @schema AdminDeleteDiscountsDiscountConditionsConditionBatchReq
+ * type: object
+ * required:
+ *   - resources
+ * properties:
+ *   resources:
+ *     description: The resources to be deleted from the discount condition
+ *     type: array
+ *     items:
+ *       required:
+ *         - id
+ *       properties:
+ *         id:
+ *           description: The id of the item
+ *           type: string
+ */
 export class AdminDeleteDiscountsDiscountConditionsConditionBatchReq {
   @IsArray()
   resources: { id: string }[]

packages/medusa/src/api/routes/admin/discounts/update-condition.ts

@@ -20,33 +20,7 @@ import { FindParams } from "../../../../types/common"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostDiscountsDiscountConditionsCondition"
- *         properties:
- *           products:
- *              type: array
- *              description: list of product IDs if the condition is applied on products.
- *              items:
- *                type: string
- *           product_types:
- *              type: array
- *              description: list of product type IDs if the condition is applied on product types.
- *              items:
- *                type: string
- *           product_collections:
- *              type: array
- *              description: list of product collection IDs if the condition is applied on product collections.
- *              items:
- *                type: string
- *           product_tags:
- *              type: array
- *              description: list of product tag IDs if the condition is applied on product tags.
- *              items:
- *                type: string
- *           customer_groups:
- *              type: array
- *              description: list of customer group IDs if the condition is applied on customer groups.
- *              items:
- *                type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -133,7 +107,38 @@ export default async (req: Request, res: Response) => {
   res.status(200).json({ discount })
 }
 
+/**
+ * @schema AdminPostDiscountsDiscountConditionsCondition
+ * type: object
+ * properties:
+ *   products:
+ *      type: array
+ *      description: list of product IDs if the condition is applied on products.
+ *      items:
+ *        type: string
+ *   product_types:
+ *      type: array
+ *      description: list of product type IDs if the condition is applied on product types.
+ *      items:
+ *        type: string
+ *   product_collections:
+ *      type: array
+ *      description: list of product collection IDs if the condition is applied on product collections.
+ *      items:
+ *        type: string
+ *   product_tags:
+ *      type: array
+ *      description: list of product tag IDs if the condition is applied on product tags.
+ *      items:
+ *        type: string
+ *   customer_groups:
+ *      type: array
+ *      description: list of customer group IDs if the condition is applied on customer groups.
+ *      items:
+ *        type: string
+ */
 // eslint-disable-next-line max-len
 export class AdminPostDiscountsDiscountConditionsCondition extends AdminUpsertConditionsReq {}
 
+// eslint-disable-next-line max-len
 export class AdminPostDiscountsDiscountConditionsConditionParams extends FindParams {}

packages/medusa/src/api/routes/admin/discounts/update-discount.ts

@@ -36,6 +36,79 @@ import { FindParams } from "../../../../types/common"
  *   content:
  *     application/json:
  *       schema:
+ *         $ref: "#/components/schemas/AdminPostDiscountsDiscountReq"
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.discounts.update(discount_id, {
+ *         code: 'TEST'
+ *       })
+ *       .then(({ discount }) => {
+ *         console.log(discount.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "code": "TEST"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
+ * tags:
+ *   - Discount
+ * responses:
+ *   200:
+ *     description: OK
+ *     content:
+ *       application/json:
+ *         schema:
+ *           type: object
+ *           properties:
+ *             discount:
+ *               $ref: "#/components/schemas/Discount"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
+ */
+export default async (req: Request, res: Response) => {
+  const { discount_id } = req.params
+
+  const discountService: DiscountService = req.scope.resolve("discountService")
+
+  const manager: EntityManager = req.scope.resolve("manager")
+  await manager.transaction(async (transactionManager) => {
+    return await discountService
+      .withTransaction(transactionManager)
+      .update(discount_id, req.validatedBody as AdminPostDiscountsDiscountReq)
+  })
+
+  const discount = await discountService.retrieve(
+    discount_id,
+    req.retrieveConfig
+  )
+
+  res.status(200).json({ discount })
+}
+
+/**
+ * @schema AdminPostDiscountsDiscountReq
  * type: object
  * properties:
  *   code:
@@ -126,76 +199,7 @@ import { FindParams } from "../../../../types/common"
  *   metadata:
  *      description: An object containing metadata of the discount
  *      type: object
- * x-codeSamples:
- *   - lang: JavaScript
- *     label: JS Client
- *     source: |
- *       import Medusa from "@medusajs/medusa-js"
- *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
- *       // must be previously logged in or use api token
- *       medusa.admin.discounts.update(discount_id, {
- *         code: 'TEST'
- *       })
- *       .then(({ discount }) => {
- *         console.log(discount.id);
- *       });
- *   - lang: Shell
- *     label: cURL
- *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/discounts/{id}' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
- *       --data-raw '{
- *           "code": "TEST"
- *       }'
- * security:
- *   - api_token: []
- *   - cookie_auth: []
- * tags:
- *   - Discount
- * responses:
- *   200:
- *     description: OK
- *     content:
- *       application/json:
- *         schema:
- *           type: object
- *           properties:
- *             discount:
- *               $ref: "#/components/schemas/Discount"
- *   "400":
- *     $ref: "#/components/responses/400_error"
- *   "401":
- *     $ref: "#/components/responses/unauthorized"
- *   "404":
- *     $ref: "#/components/responses/not_found_error"
- *   "409":
- *     $ref: "#/components/responses/invalid_state_error"
- *   "422":
- *     $ref: "#/components/responses/invalid_request_error"
- *   "500":
- *     $ref: "#/components/responses/500_error"
  */
-export default async (req: Request, res: Response) => {
-  const { discount_id } = req.params
-
-  const discountService: DiscountService = req.scope.resolve("discountService")
-
-  const manager: EntityManager = req.scope.resolve("manager")
-  await manager.transaction(async (transactionManager) => {
-    return await discountService
-      .withTransaction(transactionManager)
-      .update(discount_id, req.validatedBody as AdminPostDiscountsDiscountReq)
-  })
-
-  const discount = await discountService.retrieve(
-    discount_id,
-    req.retrieveConfig
-  )
-
-  res.status(200).json({ discount })
-}
-
 export class AdminPostDiscountsDiscountReq {
   @IsString()
   @IsOptional()

packages/medusa/src/api/routes/admin/draft-orders/create-draft-order.ts

@@ -36,93 +36,7 @@ import { IsType } from "../../../../utils/validators/is-type"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostDraftOrdersReq"
- *         required:
- *           - email
- *           - region_id
- *           - shipping_methods
- *         properties:
- *           status:
- *             description: "The status of the draft order"
- *             type: string
- *             enum: [open, completed]
- *           email:
- *             description: "The email of the customer of the draft order"
- *             type: string
- *             format: email
- *           billing_address:
- *             description: "The Address to be used for billing purposes."
- *             anyOf:
- *               - $ref: "#/components/schemas/AddressFields"
- *               - type: string
- *           shipping_address:
- *             description: "The Address to be used for shipping."
- *             anyOf:
- *               - $ref: "#/components/schemas/AddressFields"
- *               - type: string
- *           items:
- *             description: The Line Items that have been received.
- *             type: array
- *             items:
- *               type: object
- *               required:
- *                 - quantity
- *               properties:
- *                 variant_id:
- *                   description: The ID of the Product Variant to generate the Line Item from.
- *                   type: string
- *                 unit_price:
- *                   description: The potential custom price of the item.
- *                   type: integer
- *                 title:
- *                   description: The potential custom title of the item.
- *                   type: string
- *                 quantity:
- *                   description: The quantity of the Line Item.
- *                   type: integer
- *                 metadata:
- *                   description: The optional key-value map with additional details about the Line Item.
- *                   type: object
- *           region_id:
- *             description: The ID of the region for the draft order
- *             type: string
- *           discounts:
- *             description: The discounts to add on the draft order
- *             type: array
- *             items:
- *               type: object
- *               required:
- *                 - code
- *               properties:
- *                 code:
- *                   description: The code of the discount to apply
- *                   type: string
- *           customer_id:
- *             description: The ID of the customer to add on the draft order
- *             type: string
- *           no_notification_order:
- *             description: An optional flag passed to the resulting order to determine use of notifications.
- *             type: boolean
- *           shipping_methods:
- *             description: The shipping methods for the draft order
- *             type: array
- *             items:
- *               type: object
- *               required:
- *                  - option_id
- *               properties:
- *                 option_id:
- *                   description: The ID of the shipping option in use
- *                   type: string
- *                 data:
- *                   description: The optional additional data needed for the shipping method
- *                   type: object
- *                 price:
- *                   description: The potential custom price of the shipping
- *                   type: integer
- *           metadata:
- *             description: The optional key-value map with additional details about the Draft Order.
- *             type: object
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -249,6 +163,96 @@ enum Status {
   completed = "completed",
 }
 
+/**
+ * @schema AdminPostDraftOrdersReq
+ * type: object
+ * required:
+ *   - email
+ *   - region_id
+ *   - shipping_methods
+ * properties:
+ *   status:
+ *     description: "The status of the draft order"
+ *     type: string
+ *     enum: [open, completed]
+ *   email:
+ *     description: "The email of the customer of the draft order"
+ *     type: string
+ *     format: email
+ *   billing_address:
+ *     description: "The Address to be used for billing purposes."
+ *     anyOf:
+ *       - $ref: "#/components/schemas/AddressFields"
+ *       - type: string
+ *   shipping_address:
+ *     description: "The Address to be used for shipping."
+ *     anyOf:
+ *       - $ref: "#/components/schemas/AddressFields"
+ *       - type: string
+ *   items:
+ *     description: The Line Items that have been received.
+ *     type: array
+ *     items:
+ *       type: object
+ *       required:
+ *         - quantity
+ *       properties:
+ *         variant_id:
+ *           description: The ID of the Product Variant to generate the Line Item from.
+ *           type: string
+ *         unit_price:
+ *           description: The potential custom price of the item.
+ *           type: integer
+ *         title:
+ *           description: The potential custom title of the item.
+ *           type: string
+ *         quantity:
+ *           description: The quantity of the Line Item.
+ *           type: integer
+ *         metadata:
+ *           description: The optional key-value map with additional details about the Line Item.
+ *           type: object
+ *   region_id:
+ *     description: The ID of the region for the draft order
+ *     type: string
+ *   discounts:
+ *     description: The discounts to add on the draft order
+ *     type: array
+ *     items:
+ *       type: object
+ *       required:
+ *         - code
+ *       properties:
+ *         code:
+ *           description: The code of the discount to apply
+ *           type: string
+ *   customer_id:
+ *     description: The ID of the customer to add on the draft order
+ *     type: string
+ *   no_notification_order:
+ *     description: An optional flag passed to the resulting order to determine use of notifications.
+ *     type: boolean
+ *   shipping_methods:
+ *     description: The shipping methods for the draft order
+ *     type: array
+ *     items:
+ *       type: object
+ *       required:
+ *          - option_id
+ *       properties:
+ *         option_id:
+ *           description: The ID of the shipping option in use
+ *           type: string
+ *         data:
+ *           description: The optional additional data needed for the shipping method
+ *           type: object
+ *         price:
+ *           description: The potential custom price of the shipping
+ *           type: integer
+ *   metadata:
+ *     description: The optional key-value map with additional details about the Draft Order.
+ *     type: object
+ */
 export class AdminPostDraftOrdersReq {
   @IsEnum(Status)
   @IsOptional()

packages/medusa/src/api/routes/admin/draft-orders/create-line-item.ts

@@ -26,26 +26,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostDraftOrdersDraftOrderLineItemsReq"
- *         required:
- *           - quantity
- *         properties:
- *           variant_id:
- *             description: The ID of the Product Variant to generate the Line Item from.
- *             type: string
- *           unit_price:
- *             description: The potential custom price of the item.
- *             type: integer
- *           title:
- *             description: The potential custom title of the item.
- *             type: string
- *             default: "Custom item"
- *           quantity:
- *             description: The quantity of the Line Item.
- *             type: integer
- *           metadata:
- *             description: The optional key-value map with additional details about the Line Item.
- *             type: object
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -162,6 +143,29 @@ export default async (req, res) => {
   })
 }
 
+/**
+ * @schema AdminPostDraftOrdersDraftOrderLineItemsReq
+ * type: object
+ * required:
+ *   - quantity
+ * properties:
+ *   variant_id:
+ *     description: The ID of the Product Variant to generate the Line Item from.
+ *     type: string
+ *   unit_price:
+ *     description: The potential custom price of the item.
+ *     type: integer
+ *   title:
+ *     description: The potential custom title of the item.
+ *     type: string
+ *     default: "Custom item"
+ *   quantity:
+ *     description: The quantity of the Line Item.
+ *     type: integer
+ *   metadata:
+ *     description: The optional key-value map with additional details about the Line Item.
+ *     type: object
+ */
 export class AdminPostDraftOrdersDraftOrderLineItemsReq {
   @IsString()
   @IsOptional()

packages/medusa/src/api/routes/admin/draft-orders/update-draft-order.ts

@@ -32,48 +32,7 @@ import { IsType } from "../../../../utils/validators/is-type"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostDraftOrdersDraftOrderReq"
- *         properties:
- *           region_id:
- *             type: string
- *             description: The ID of the Region to create the Draft Order in.
- *           country_code:
- *             type: string
- *             description: "The 2 character ISO code for the Country."
- *             externalDocs:
- *                url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
- *                description: See a list of codes.
- *           email:
- *             type: string
- *             description: "An email to be used on the Draft Order."
- *             format: email
- *           billing_address:
- *             description: "The Address to be used for billing purposes."
- *             anyOf:
- *               - $ref: "#/components/schemas/AddressFields"
- *               - type: string
- *           shipping_address:
- *             description: "The Address to be used for shipping."
- *             anyOf:
- *               - $ref: "#/components/schemas/AddressFields"
- *               - type: string
- *           discounts:
- *             description: "An array of Discount codes to add to the Draft Order."
- *             type: array
- *             items:
- *               type: object
- *               required:
- *                 - code
- *               properties:
- *                 code:
- *                   description: "The code that a Discount is identifed by."
- *                   type: string
- *           no_notification_order:
- *             description: "An optional flag passed to the resulting order to determine use of notifications."
- *             type: boolean
- *           customer_id:
- *             description: "The ID of the Customer to associate the Draft Order with."
- *             type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -182,6 +141,51 @@ export default async (req, res) => {
   res.status(200).json({ draft_order: draftOrder })
 }
 
+/**
+ * @schema AdminPostDraftOrdersDraftOrderReq
+ * type: object
+ * properties:
+ *   region_id:
+ *     type: string
+ *     description: The ID of the Region to create the Draft Order in.
+ *   country_code:
+ *     type: string
+ *     description: "The 2 character ISO code for the Country."
+ *     externalDocs:
+ *        url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
+ *        description: See a list of codes.
+ *   email:
+ *     type: string
+ *     description: "An email to be used on the Draft Order."
+ *     format: email
+ *   billing_address:
+ *     description: "The Address to be used for billing purposes."
+ *     anyOf:
+ *       - $ref: "#/components/schemas/AddressFields"
+ *       - type: string
+ *   shipping_address:
+ *     description: "The Address to be used for shipping."
+ *     anyOf:
+ *       - $ref: "#/components/schemas/AddressFields"
+ *       - type: string
+ *   discounts:
+ *     description: "An array of Discount codes to add to the Draft Order."
+ *     type: array
+ *     items:
+ *       type: object
+ *       required:
+ *         - code
+ *       properties:
+ *         code:
+ *           description: "The code that a Discount is identifed by."
+ *           type: string
+ *   no_notification_order:
+ *     description: "An optional flag passed to the resulting order to determine use of notifications."
+ *     type: boolean
+ *   customer_id:
+ *     description: "The ID of the Customer to associate the Draft Order with."
+ *     type: string
+ */
 export class AdminPostDraftOrdersDraftOrderReq {
   @IsString()
   @IsOptional()

packages/medusa/src/api/routes/admin/draft-orders/update-line-item.ts

@@ -25,20 +25,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostDraftOrdersDraftOrderLineItemsItemReq"
- *         properties:
- *           unit_price:
- *             description: The potential custom price of the item.
- *             type: integer
- *           title:
- *             description: The potential custom title of the item.
- *             type: string
- *           quantity:
- *             description: The quantity of the Line Item.
- *             type: integer
- *           metadata:
- *             description: The optional key-value map with additional details about the Line Item.
- *             type: object
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -157,6 +144,23 @@ export default async (req, res) => {
   })
 }
 
+/**
+ * @schema AdminPostDraftOrdersDraftOrderLineItemsItemReq
+ * type: object
+ * properties:
+ *   unit_price:
+ *     description: The potential custom price of the item.
+ *     type: integer
+ *   title:
+ *     description: The potential custom title of the item.
+ *     type: string
+ *   quantity:
+ *     description: The quantity of the Line Item.
+ *     type: integer
+ *   metadata:
+ *     description: The optional key-value map with additional details about the Line Item.
+ *     type: object
+ */
 export class AdminPostDraftOrdersDraftOrderLineItemsItemReq {
   @IsString()
   @IsOptional()

packages/medusa/src/api/routes/admin/gift-cards/create-gift-card.ts

@@ -15,26 +15,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostGiftCardsReq"
- *         required:
- *           - region_id
- *         properties:
- *           value:
- *             type: integer
- *             description: The value (excluding VAT) that the Gift Card should represent.
- *           is_disabled:
- *             type: boolean
- *             description: Whether the Gift Card is disabled on creation. You will have to enable it later to make it available to Customers.
- *           ends_at:
- *             type: string
- *             format: date-time
- *             description: The time at which the Gift Card should no longer be available.
- *           region_id:
- *             description: The ID of the Region in which the Gift Card can be used.
- *             type: string
- *           metadata:
- *             description: An optional set of key-value pairs to hold additional information.
- *             type: object
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -103,6 +84,29 @@ export default async (req, res) => {
   res.status(200).json({ gift_card: giftCard })
 }
 
+/**
+ * @schema AdminPostGiftCardsReq
+ * type: object
+ * required:
+ *   - region_id
+ * properties:
+ *   value:
+ *     type: integer
+ *     description: The value (excluding VAT) that the Gift Card should represent.
+ *   is_disabled:
+ *     type: boolean
+ *     description: Whether the Gift Card is disabled on creation. You will have to enable it later to make it available to Customers.
+ *   ends_at:
+ *     type: string
+ *     format: date-time
+ *     description: The time at which the Gift Card should no longer be available.
+ *   region_id:
+ *     description: The ID of the Region in which the Gift Card can be used.
+ *     type: string
+ *   metadata:
+ *     description: An optional set of key-value pairs to hold additional information.
+ *     type: object
+ */
 export class AdminPostGiftCardsReq {
   @IsOptional()
   @IsInt()

packages/medusa/src/api/routes/admin/gift-cards/update-gift-card.ts

@@ -18,24 +18,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostGiftCardsGiftCardReq"
- *         properties:
- *           balance:
- *             type: integer
- *             description: The value (excluding VAT) that the Gift Card should represent.
- *           is_disabled:
- *             type: boolean
- *             description: Whether the Gift Card is disabled on creation. You will have to enable it later to make it available to Customers.
- *           ends_at:
- *             type: string
- *             format: date-time
- *             description: The time at which the Gift Card should no longer be available.
- *           region_id:
- *             description: The ID of the Region in which the Gift Card can be used.
- *             type: string
- *           metadata:
- *             description: An optional set of key-value pairs to hold additional information.
- *             type: object
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -108,6 +91,27 @@ export default async (req, res) => {
   res.status(200).json({ gift_card: giftCard })
 }
 
+/**
+ * @schema AdminPostGiftCardsGiftCardReq
+ * type: object
+ * properties:
+ *   balance:
+ *     type: integer
+ *     description: The value (excluding VAT) that the Gift Card should represent.
+ *   is_disabled:
+ *     type: boolean
+ *     description: Whether the Gift Card is disabled on creation. You will have to enable it later to make it available to Customers.
+ *   ends_at:
+ *     type: string
+ *     format: date-time
+ *     description: The time at which the Gift Card should no longer be available.
+ *   region_id:
+ *     description: The ID of the Region in which the Gift Card can be used.
+ *     type: string
+ *   metadata:
+ *     description: An optional set of key-value pairs to hold additional information.
+ *     type: object
+ */
 export class AdminPostGiftCardsGiftCardReq {
   @IsOptional()
   @IsInt()

packages/medusa/src/api/routes/admin/invites/accept-invite.ts

@@ -14,32 +14,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostInvitesInviteAcceptReq"
- *         required:
- *           - token
- *           - user
- *         properties:
- *           token:
- *             description: "The invite token provided by the admin."
- *             type: string
- *           user:
- *             description: "The User to create."
- *             type: object
- *             required:
- *               - first_name
- *               - last_name
- *               - password
- *             properties:
- *               first_name:
- *                 type: string
- *                 description: the first name of the User
- *               last_name:
- *                 type: string
- *                 description: the last name of the User
- *               password:
- *                 description: The desired password for the User
- *                 type: string
- *                 format: password
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -122,6 +97,35 @@ export class AdminPostInvitesInviteAcceptUserReq {
   password: string
 }
 
+/**
+ * @schema AdminPostInvitesInviteAcceptReq
+ * type: object
+ * required:
+ *   - token
+ *   - user
+ * properties:
+ *   token:
+ *     description: "The invite token provided by the admin."
+ *     type: string
+ *   user:
+ *     description: "The User to create."
+ *     type: object
+ *     required:
+ *       - first_name
+ *       - last_name
+ *       - password
+ *     properties:
+ *       first_name:
+ *         type: string
+ *         description: the first name of the User
+ *       last_name:
+ *         type: string
+ *         description: the last name of the User
+ *       password:
+ *         description: The desired password for the User
+ *         type: string
+ *         format: password
+ */
 export class AdminPostInvitesInviteAcceptReq {
   @IsString()
   @IsNotEmpty()

packages/medusa/src/api/routes/admin/invites/create-invite.ts

@@ -15,19 +15,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostInvitesReq"
- *         required:
- *           - user
- *           - role
- *         properties:
- *           user:
- *             description: "The email for the user to be created."
- *             type: string
- *             format: email
- *           role:
- *             description: "The role of the user to be created."
- *             type: string
- *             enum: [admin, member, developer]
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -90,6 +78,23 @@ export default async (req, res) => {
 
   res.sendStatus(200)
 }
+
+/**
+ * @schema AdminPostInvitesReq
+ * type: object
+ * required:
+ *   - user
+ *   - role
+ * properties:
+ *   user:
+ *     description: "The email for the user to be created."
+ *     type: string
+ *     format: email
+ *   role:
+ *     description: "The role of the user to be created."
+ *     type: string
+ *     enum: [admin, member, developer]
+ */
 export class AdminPostInvitesReq {
   @IsEmail()
   user: string

packages/medusa/src/api/routes/admin/notes/create-note.ts

@@ -14,21 +14,7 @@ import { EntityManager } from "typeorm"
  *  content:
  *    application/json:
  *      schema:
- *        type: object
+ *        $ref: "#/components/schemas/AdminPostNotesReq"
- *        required:
- *          - resource_id
- *          - resource_type
- *          - value
- *        properties:
- *          resource_id:
- *            type: string
- *            description: The ID of the resource which the Note relates to.
- *          resource_type:
- *            type: string
- *            description: The type of resource which the Note relates to.
- *          value:
- *            type: string
- *            description: The content of the Note to create.
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -104,6 +90,24 @@ export default async (req, res) => {
   res.status(200).json({ note: result })
 }
 
+/**
+ * @schema AdminPostNotesReq
+ * type: object
+ * required:
+ *   - resource_id
+ *   - resource_type
+ *   - value
+ * properties:
+ *   resource_id:
+ *     type: string
+ *     description: The ID of the resource which the Note relates to.
+ *   resource_type:
+ *     type: string
+ *     description: The type of resource which the Note relates to.
+ *   value:
+ *     type: string
+ *     description: The content of the Note to create.
+ */
 export class AdminPostNotesReq {
   @IsString()
   @IsNotEmpty()

packages/medusa/src/api/routes/admin/notes/update-note.ts

@@ -15,13 +15,7 @@ import { EntityManager } from "typeorm"
  *  content:
  *    application/json:
  *      schema:
- *        type: object
+ *        $ref: "#/components/schemas/AdminPostNotesNoteReq"
- *        required:
- *          - value
- *        properties:
- *          value:
- *            type: string
- *            description: The updated description of the Note.
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -88,6 +82,16 @@ export default async (req, res) => {
   res.status(200).json({ note })
 }
 
+/**
+ * @schema AdminPostNotesNoteReq
+ * type: object
+ * required:
+ *   - value
+ * properties:
+ *   value:
+ *     type: string
+ *     description: The updated description of the Note.
+ */
 export class AdminPostNotesNoteReq {
   @IsString()
   value: string

packages/medusa/src/api/routes/admin/notifications/resend-notification.ts

@@ -21,11 +21,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostNotificationsNotificationResendReq"
- *         properties:
- *           to:
- *             description: "A new address or user identifier that the Notification should be sent to"
- *             type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -103,6 +99,14 @@ export default async (req, res) => {
   res.json({ notification })
 }
 
+/**
+ * @schema AdminPostNotificationsNotificationResendReq
+ * type: object
+ * properties:
+ *   to:
+ *     description: "A new address or user identifier that the Notification should be sent to"
+ *     type: string
+ */
 export class AdminPostNotificationsNotificationResendReq {
   @IsOptional()
   @IsString()

packages/medusa/src/api/routes/admin/order-edits/add-line-item.ts

@@ -19,20 +19,7 @@ import {
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostOrderEditsEditLineItemsReq"
- *         required:
- *           - variant_id
- *           - quantity
- *         properties:
- *           variant_id:
- *             description: The ID of the variant ID to add
- *             type: string
- *           quantity:
- *             description: The quantity to add
- *             type: number
- *           metadata:
- *             description: An optional set of key-value pairs to hold additional information.
- *             type: object
  * x-authenticated: true
  * x-codeSamples:
  *   - lang: JavaScript
@@ -112,6 +99,23 @@ export default async (req: Request, res: Response) => {
   })
 }
 
+/**
+ * @schema AdminPostOrderEditsEditLineItemsReq
+ * type: object
+ * required:
+ *   - variant_id
+ *   - quantity
+ * properties:
+ *   variant_id:
+ *     description: The ID of the variant ID to add
+ *     type: string
+ *   quantity:
+ *     description: The quantity to add
+ *     type: number
+ *   metadata:
+ *     description: An optional set of key-value pairs to hold additional information.
+ *     type: object
+ */
 export class AdminPostOrderEditsEditLineItemsReq {
   @IsString()
   variant_id: string

packages/medusa/src/api/routes/admin/order-edits/create-order-edit.ts

@@ -16,16 +16,7 @@ import {
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostOrderEditsReq"
- *         required:
- *           - order_id
- *         properties:
- *           order_id:
- *             description: The ID of the order to create the edit for.
- *             type: string
- *           internal_note:
- *             description: An optional note to create for the order edit.
- *             type: string
  * x-authenticated: true
  * x-codeSamples:
  *   - lang: JavaScript
@@ -99,6 +90,19 @@ export default async (req: Request, res: Response) => {
   return res.json({ order_edit: orderEdit })
 }
 
+/**
+ * @schema AdminPostOrderEditsReq
+ * type: object
+ * required:
+ *   - order_id
+ * properties:
+ *   order_id:
+ *     description: The ID of the order to create the edit for.
+ *     type: string
+ *   internal_note:
+ *     description: An optional note to create for the order edit.
+ *     type: string
+ */
 export class AdminPostOrderEditsReq {
   @IsString()
   order_id: string

packages/medusa/src/api/routes/admin/order-edits/update-order-edit-line-item.ts

@@ -20,13 +20,7 @@ import {
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostOrderEditsEditLineItemsLineItemReq"
- *         required:
- *           - quantity
- *         properties:
- *           quantity:
- *             description: The quantity to update
- *             type: number
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -103,6 +97,16 @@ export default async (req: Request, res: Response) => {
   })
 }
 
+/**
+ * @schema AdminPostOrderEditsEditLineItemsLineItemReq
+ * type: object
+ * required:
+ *   - quantity
+ * properties:
+ *   quantity:
+ *     description: The quantity to update
+ *     type: number
+ */
 export class AdminPostOrderEditsEditLineItemsLineItemReq {
   @IsNumber()
   quantity: number

packages/medusa/src/api/routes/admin/order-edits/update-order-edit.ts

@@ -20,11 +20,7 @@ import {
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostOrderEditsOrderEditReq"
- *         properties:
- *           internal_note:
- *             description: An optional note to create or update for the order edit.
- *             type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -103,6 +99,14 @@ export default async (req: Request, res: Response) => {
   res.status(200).json({ order_edit: orderEdit })
 }
 
+/**
+ * @schema AdminPostOrderEditsOrderEditReq
+ * type: object
+ * properties:
+ *   internal_note:
+ *     description: An optional note to create or update for the order edit.
+ *     type: string
+ */
 export class AdminPostOrderEditsOrderEditReq {
   @IsOptional()
   @IsString()

packages/medusa/src/api/routes/admin/orders/create-claim-shipment.ts

@@ -18,18 +18,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostOrdersOrderClaimsClaimShipmentsReq"
- *         required:
- *           - fulfillment_id
- *         properties:
- *           fulfillment_id:
- *             description: The ID of the Fulfillment.
- *             type: string
- *           tracking_numbers:
- *             description: The tracking numbers for the shipment.
- *             type: array
- *             items:
- *               type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -110,6 +99,21 @@ export default async (req, res) => {
   res.json({ order })
 }
 
+/**
+ * @schema AdminPostOrdersOrderClaimsClaimShipmentsReq
+ * type: object
+ * required:
+ *   - fulfillment_id
+ * properties:
+ *   fulfillment_id:
+ *     description: The ID of the Fulfillment.
+ *     type: string
+ *   tracking_numbers:
+ *     description: The tracking numbers for the shipment.
+ *     type: array
+ *     items:
+ *       type: string
+ */
 export class AdminPostOrdersOrderClaimsClaimShipmentsReq {
   @IsString()
   @IsNotEmpty()

packages/medusa/src/api/routes/admin/orders/create-claim.ts

@@ -31,102 +31,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostOrdersOrderClaimsReq"
- *         required:
- *           - type
- *           - claim_items
- *         properties:
- *           type:
- *             description: "The type of the Claim. This will determine how the Claim is treated: `replace` Claims will result in a Fulfillment with new items being created, while a `refund` Claim will refund the amount paid for the claimed items."
- *             type: string
- *             enum:
- *               - replace
- *               - refund
- *           claim_items:
- *             description: The Claim Items that the Claim will consist of.
- *             type: array
- *             items:
- *               required:
- *                 - item_id
- *                 - quantity
- *               properties:
- *                 item_id:
- *                   description: The ID of the Line Item that will be claimed.
- *                   type: string
- *                 quantity:
- *                   description: The number of items that will be returned
- *                   type: integer
- *                 note:
- *                   description: Short text describing the Claim Item in further detail.
- *                   type: string
- *                 reason:
- *                   description: The reason for the Claim
- *                   type: string
- *                   enum:
- *                     - missing_item
- *                     - wrong_item
- *                     - production_failure
- *                     - other
- *                 tags:
- *                   description: A list o tags to add to the Claim Item
- *                   type: array
- *                   items:
- *                     type: string
- *                 images:
- *                   description: A list of image URL's that will be associated with the Claim
- *                   items:
- *                     type: string
- *           return_shipping:
- *              description: Optional details for the Return Shipping Method, if the items are to be sent back.
- *              type: object
- *              properties:
- *                option_id:
- *                  type: string
- *                  description: The ID of the Shipping Option to create the Shipping Method from.
- *                price:
- *                  type: integer
- *                  description: The price to charge for the Shipping Method.
- *           additional_items:
- *              description: The new items to send to the Customer when the Claim type is Replace.
- *              type: array
- *              items:
- *                required:
- *                  - variant_id
- *                  - quantity
- *                properties:
- *                  variant_id:
- *                    description: The ID of the Product Variant to ship.
- *                    type: string
- *                  quantity:
- *                    description: The quantity of the Product Variant to ship.
- *                    type: integer
- *           shipping_methods:
- *              description: The Shipping Methods to send the additional Line Items with.
- *              type: array
- *              items:
- *                 properties:
- *                   id:
- *                     description: The ID of an existing Shipping Method
- *                     type: string
- *                   option_id:
- *                     description: The ID of the Shipping Option to create a Shipping Method from
- *                     type: string
- *                   price:
- *                     description: The price to charge for the Shipping Method
- *                     type: integer
- *           shipping_address:
- *              type: object
- *              description: "An optional shipping address to send the claim to. Defaults to the parent order's shipping address"
- *              $ref: "#/components/schemas/Address"
- *           refund_amount:
- *              description: The amount to refund the Customer when the Claim type is `refund`.
- *              type: integer
- *           no_notification:
- *              description: If set to true no notification will be send related to this Claim.
- *              type: boolean
- *           metadata:
- *              description: An optional set of key-value pairs to hold additional information.
- *              type: object
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -394,6 +299,105 @@ export default async (req, res) => {
   res.status(idempotencyKey.response_code).json(idempotencyKey.response_body)
 }
 
+/**
+ * @schema AdminPostOrdersOrderClaimsReq
+ * type: object
+ * required:
+ *   - type
+ *   - claim_items
+ * properties:
+ *   type:
+ *     description: "The type of the Claim. This will determine how the Claim is treated: `replace` Claims will result in a Fulfillment with new items being created, while a `refund` Claim will refund the amount paid for the claimed items."
+ *     type: string
+ *     enum:
+ *       - replace
+ *       - refund
+ *   claim_items:
+ *     description: The Claim Items that the Claim will consist of.
+ *     type: array
+ *     items:
+ *       required:
+ *         - item_id
+ *         - quantity
+ *       properties:
+ *         item_id:
+ *           description: The ID of the Line Item that will be claimed.
+ *           type: string
+ *         quantity:
+ *           description: The number of items that will be returned
+ *           type: integer
+ *         note:
+ *           description: Short text describing the Claim Item in further detail.
+ *           type: string
+ *         reason:
+ *           description: The reason for the Claim
+ *           type: string
+ *           enum:
+ *             - missing_item
+ *             - wrong_item
+ *             - production_failure
+ *             - other
+ *         tags:
+ *           description: A list o tags to add to the Claim Item
+ *           type: array
+ *           items:
+ *             type: string
+ *         images:
+ *           description: A list of image URL's that will be associated with the Claim
+ *           items:
+ *             type: string
+ *   return_shipping:
+ *      description: Optional details for the Return Shipping Method, if the items are to be sent back.
+ *      type: object
+ *      properties:
+ *        option_id:
+ *          type: string
+ *          description: The ID of the Shipping Option to create the Shipping Method from.
+ *        price:
+ *          type: integer
+ *          description: The price to charge for the Shipping Method.
+ *   additional_items:
+ *      description: The new items to send to the Customer when the Claim type is Replace.
+ *      type: array
+ *      items:
+ *        required:
+ *          - variant_id
+ *          - quantity
+ *        properties:
+ *          variant_id:
+ *            description: The ID of the Product Variant to ship.
+ *            type: string
+ *          quantity:
+ *            description: The quantity of the Product Variant to ship.
+ *            type: integer
+ *   shipping_methods:
+ *      description: The Shipping Methods to send the additional Line Items with.
+ *      type: array
+ *      items:
+ *         properties:
+ *           id:
+ *             description: The ID of an existing Shipping Method
+ *             type: string
+ *           option_id:
+ *             description: The ID of the Shipping Option to create a Shipping Method from
+ *             type: string
+ *           price:
+ *             description: The price to charge for the Shipping Method
+ *             type: integer
+ *   shipping_address:
+ *      type: object
+ *      description: "An optional shipping address to send the claim to. Defaults to the parent order's shipping address"
+ *      $ref: "#/components/schemas/Address"
+ *   refund_amount:
+ *      description: The amount to refund the Customer when the Claim type is `refund`.
+ *      type: integer
+ *   no_notification:
+ *      description: If set to true no notification will be send related to this Claim.
+ *      type: boolean
+ *   metadata:
+ *      description: An optional set of key-value pairs to hold additional information.
+ *      type: object
+ */
 export class AdminPostOrdersOrderClaimsReq {
   @IsEnum(ClaimType)
   @IsNotEmpty()

packages/medusa/src/api/routes/admin/orders/create-fulfillment.ts

@@ -28,30 +28,7 @@ import { optionalBooleanMapper } from "../../../../utils/validators/is-boolean"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostOrdersOrderFulfillmentsReq"
- *         required:
- *           - items
- *         properties:
- *           items:
- *             description: The Line Items to include in the Fulfillment.
- *             type: array
- *             items:
- *               required:
- *                 - item_id
- *                 - quantity
- *               properties:
- *                 item_id:
- *                   description: The ID of Line Item to fulfill.
- *                   type: string
- *                 quantity:
- *                   description: The quantity of the Line Item to fulfill.
- *                   type: integer
- *           no_notification:
- *             description: If set to true no notification will be send related to this Swap.
- *             type: boolean
- *           metadata:
- *             description: An optional set of key-value pairs to hold additional information.
- *             type: object
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -140,6 +117,33 @@ export default async (req, res) => {
   res.json({ order })
 }
 
+/**
+ * @schema AdminPostOrdersOrderFulfillmentsReq
+ * type: object
+ * required:
+ *   - items
+ * properties:
+ *   items:
+ *     description: The Line Items to include in the Fulfillment.
+ *     type: array
+ *     items:
+ *       required:
+ *         - item_id
+ *         - quantity
+ *       properties:
+ *         item_id:
+ *           description: The ID of Line Item to fulfill.
+ *           type: string
+ *         quantity:
+ *           description: The quantity of the Line Item to fulfill.
+ *           type: integer
+ *   no_notification:
+ *     description: If set to true no notification will be send related to this Swap.
+ *     type: boolean
+ *   metadata:
+ *     description: An optional set of key-value pairs to hold additional information.
+ *     type: object
+ */
 export class AdminPostOrdersOrderFulfillmentsReq {
   @IsArray()
   @ValidateNested({ each: true })

packages/medusa/src/api/routes/admin/orders/create-shipment.ts

@@ -24,21 +24,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostOrdersOrderShipmentReq"
- *         required:
- *           - fulfillment_id
- *         properties:
- *           fulfillment_id:
- *             description: The ID of the Fulfillment.
- *             type: string
- *           tracking_numbers:
- *             description: The tracking numbers for the shipment.
- *             type: array
- *             items:
- *               type: string
- *           no_notification:
- *             description: If set to true no notification will be send related to this Shipment.
- *             type: boolean
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -121,6 +107,24 @@ export default async (req, res) => {
   res.json({ order })
 }
 
+/**
+ * @schema AdminPostOrdersOrderShipmentReq
+ * type: object
+ * required:
+ *   - fulfillment_id
+ * properties:
+ *   fulfillment_id:
+ *     description: The ID of the Fulfillment.
+ *     type: string
+ *   tracking_numbers:
+ *     description: The tracking numbers for the shipment.
+ *     type: array
+ *     items:
+ *       type: string
+ *   no_notification:
+ *     description: If set to true no notification will be send related to this Shipment.
+ *     type: boolean
+ */
 export class AdminPostOrdersOrderShipmentReq {
   @IsString()
   @IsNotEmpty()

packages/medusa/src/api/routes/admin/orders/create-swap-shipment.ts

@@ -24,21 +24,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostOrdersOrderSwapsSwapShipmentsReq"
- *         required:
- *           - fulfillment_id
- *         properties:
- *           fulfillment_id:
- *             description: The ID of the Fulfillment.
- *             type: string
- *           tracking_numbers:
- *             description: The tracking numbers for the shipment.
- *             type: array
- *             items:
- *               type: string
- *           no_notification:
- *             description: If set to true no notification will be sent related to this Claim.
- *             type: boolean
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -118,6 +104,24 @@ export default async (req, res) => {
   res.json({ order })
 }
 
+/**
+ * @schema AdminPostOrdersOrderSwapsSwapShipmentsReq
+ * type: object
+ * required:
+ *   - fulfillment_id
+ * properties:
+ *   fulfillment_id:
+ *     description: The ID of the Fulfillment.
+ *     type: string
+ *   tracking_numbers:
+ *     description: The tracking numbers for the shipment.
+ *     type: array
+ *     items:
+ *       type: string
+ *   no_notification:
+ *     description: If set to true no notification will be sent related to this Claim.
+ *     type: boolean
+ */
 export class AdminPostOrdersOrderSwapsSwapShipmentsReq {
   @IsString()
   @IsNotEmpty()

packages/medusa/src/api/routes/admin/orders/create-swap.ts

@@ -35,77 +35,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostOrdersOrderSwapsReq"
- *         required:
- *           - return_items
- *         properties:
- *           return_items:
- *             description: The Line Items to return as part of the Swap.
- *             type: array
- *             items:
- *               required:
- *                 - item_id
- *                 - quantity
- *               properties:
- *                 item_id:
- *                   description: The ID of the Line Item that will be claimed.
- *                   type: string
- *                 quantity:
- *                   description: The number of items that will be returned
- *                   type: integer
- *                 reason_id:
- *                   description: The ID of the Return Reason to use.
- *                   type: string
- *                 note:
- *                   description: An optional note with information about the Return.
- *                   type: string
- *           return_shipping:
- *             description: How the Swap will be returned.
- *             type: object
- *             required:
- *               - option_id
- *             properties:
- *               option_id:
- *                 type: string
- *                 description: The ID of the Shipping Option to create the Shipping Method from.
- *               price:
- *                 type: integer
- *                 description: The price to charge for the Shipping Method.
- *           additional_items:
- *             description: The new items to send to the Customer.
- *             type: array
- *             items:
- *               required:
- *                 - variant_id
- *                 - quantity
- *               properties:
- *                 variant_id:
- *                   description: The ID of the Product Variant to ship.
- *                   type: string
- *                 quantity:
- *                   description: The quantity of the Product Variant to ship.
- *                   type: integer
- *           custom_shipping_options:
- *             description: The custom shipping options to potentially create a Shipping Method from.
- *             type: array
- *             items:
- *               required:
- *                 - option_id
- *                 - price
- *               properties:
- *                 option_id:
- *                   description: The ID of the Shipping Option to override with a custom price.
- *                   type: string
- *                 price:
- *                   description: The custom price of the Shipping Option.
- *                   type: integer
- *           no_notification:
- *             description: If set to true no notification will be send related to this Swap.
- *             type: boolean
- *           allow_backorder:
- *             description: If true, swaps can be completed with items out of stock
- *             type: boolean
- *             default: true
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -323,6 +253,80 @@ export default async (req, res) => {
   res.status(idempotencyKey.response_code).json(idempotencyKey.response_body)
 }
 
+/**
+ * @schema AdminPostOrdersOrderSwapsReq
+ * type: object
+ * required:
+ *   - return_items
+ * properties:
+ *   return_items:
+ *     description: The Line Items to return as part of the Swap.
+ *     type: array
+ *     items:
+ *       required:
+ *         - item_id
+ *         - quantity
+ *       properties:
+ *         item_id:
+ *           description: The ID of the Line Item that will be claimed.
+ *           type: string
+ *         quantity:
+ *           description: The number of items that will be returned
+ *           type: integer
+ *         reason_id:
+ *           description: The ID of the Return Reason to use.
+ *           type: string
+ *         note:
+ *           description: An optional note with information about the Return.
+ *           type: string
+ *   return_shipping:
+ *     description: How the Swap will be returned.
+ *     type: object
+ *     required:
+ *       - option_id
+ *     properties:
+ *       option_id:
+ *         type: string
+ *         description: The ID of the Shipping Option to create the Shipping Method from.
+ *       price:
+ *         type: integer
+ *         description: The price to charge for the Shipping Method.
+ *   additional_items:
+ *     description: The new items to send to the Customer.
+ *     type: array
+ *     items:
+ *       required:
+ *         - variant_id
+ *         - quantity
+ *       properties:
+ *         variant_id:
+ *           description: The ID of the Product Variant to ship.
+ *           type: string
+ *         quantity:
+ *           description: The quantity of the Product Variant to ship.
+ *           type: integer
+ *   custom_shipping_options:
+ *     description: The custom shipping options to potentially create a Shipping Method from.
+ *     type: array
+ *     items:
+ *       required:
+ *         - option_id
+ *         - price
+ *       properties:
+ *         option_id:
+ *           description: The ID of the Shipping Option to override with a custom price.
+ *           type: string
+ *         price:
+ *           description: The custom price of the Shipping Option.
+ *           type: integer
+ *   no_notification:
+ *     description: If set to true no notification will be send related to this Swap.
+ *     type: boolean
+ *   allow_backorder:
+ *     description: If true, swaps can be completed with items out of stock
+ *     type: boolean
+ *     default: true
+ */
 export class AdminPostOrdersOrderSwapsReq {
   @IsArray()
   @IsNotEmpty()

packages/medusa/src/api/routes/admin/orders/fulfill-claim.ts

@@ -18,14 +18,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostOrdersOrderClaimsClaimFulfillmentsReq"
- *         properties:
- *           metadata:
- *             description: An optional set of key-value pairs to hold additional information.
- *             type: object
- *           no_notification:
- *             description: If set to true no notification will be send related to this Claim.
- *             type: boolean
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -97,6 +90,17 @@ export default async (req, res) => {
   res.status(200).json({ order })
 }
 
+/**
+ * @schema AdminPostOrdersOrderClaimsClaimFulfillmentsReq
+ * type: object
+ * properties:
+ *   metadata:
+ *     description: An optional set of key-value pairs to hold additional information.
+ *     type: object
+ *   no_notification:
+ *     description: If set to true no notification will be send related to this Claim.
+ *     type: boolean
+ */
 export class AdminPostOrdersOrderClaimsClaimFulfillmentsReq {
   @IsObject()
   @IsOptional()

packages/medusa/src/api/routes/admin/orders/fulfill-swap.ts

@@ -18,14 +18,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostOrdersOrderSwapsSwapFulfillmentsReq"
- *         properties:
- *           metadata:
- *             description: An optional set of key-value pairs to hold additional information.
- *             type: object
- *           no_notification:
- *             description: If set to true no notification will be send related to this Claim.
- *             type: boolean
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -97,6 +90,17 @@ export default async (req, res) => {
   res.status(200).json({ order })
 }
 
+/**
+ * @schema AdminPostOrdersOrderSwapsSwapFulfillmentsReq
+ * type: object
+ * properties:
+ *   metadata:
+ *     description: An optional set of key-value pairs to hold additional information.
+ *     type: object
+ *   no_notification:
+ *     description: If set to true no notification will be send related to this Claim.
+ *     type: boolean
+ */
 export class AdminPostOrdersOrderSwapsSwapFulfillmentsReq {
   @IsObject()
   @IsOptional()

packages/medusa/src/api/routes/admin/orders/refund-payment.ts

@@ -23,23 +23,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostOrdersOrderRefundsReq"
- *         required:
- *           - amount
- *           - reason
- *         properties:
- *           amount:
- *             description: The amount to refund.
- *             type: integer
- *           reason:
- *             description: The reason for the Refund.
- *             type: string
- *           note:
- *             description: A note with additional details about the Refund.
- *             type: string
- *           no_notification:
- *             description: If set to true no notification will be send related to this Refund.
- *             type: boolean
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -116,6 +100,26 @@ export default async (req, res) => {
   res.status(200).json({ order })
 }
 
+/**
+ * @schema AdminPostOrdersOrderRefundsReq
+ * type: object
+ * required:
+ *   - amount
+ *   - reason
+ * properties:
+ *   amount:
+ *     description: The amount to refund.
+ *     type: integer
+ *   reason:
+ *     description: The reason for the Refund.
+ *     type: string
+ *   note:
+ *     description: A note with additional details about the Refund.
+ *     type: string
+ *   no_notification:
+ *     description: If set to true no notification will be send related to this Refund.
+ *     type: boolean
+ */
 export class AdminPostOrdersOrderRefundsReq {
   @IsInt()
   @IsNotEmpty()

packages/medusa/src/api/routes/admin/orders/request-return.ts

@@ -32,53 +32,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostOrdersOrderReturnsReq"
- *         required:
- *           - items
- *         properties:
- *           items:
- *             description: The Line Items that will be returned.
- *             type: array
- *             items:
- *               required:
- *                 - item_id
- *                 - quantity
- *               properties:
- *                 item_id:
- *                   description: The ID of the Line Item.
- *                   type: string
- *                 reason_id:
- *                   description: The ID of the Return Reason to use.
- *                   type: string
- *                 note:
- *                   description: An optional note with information about the Return.
- *                   type: string
- *                 quantity:
- *                   description: The quantity of the Line Item.
- *                   type: integer
- *           return_shipping:
- *             description: The Shipping Method to be used to handle the return shipment.
- *             type: object
- *             properties:
- *               option_id:
- *                 type: string
- *                 description: The ID of the Shipping Option to create the Shipping Method from.
- *               price:
- *                 type: integer
- *                 description: The price to charge for the Shipping Method.
- *           note:
- *             description: An optional note with information about the Return.
- *             type: string
- *           receive_now:
- *             description: A flag to indicate if the Return should be registerd as received immediately.
- *             type: boolean
- *             default: false
- *           no_notification:
- *             description: A flag to indicate if no notifications should be emitted related to the requested Return.
- *             type: boolean
- *           refund:
- *             description: The amount to refund.
- *             type: integer
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -333,6 +287,56 @@ type ReturnObj = {
   no_notification?: boolean
 }
 
+/**
+ * @schema AdminPostOrdersOrderReturnsReq
+ * type: object
+ * required:
+ *   - items
+ * properties:
+ *   items:
+ *     description: The Line Items that will be returned.
+ *     type: array
+ *     items:
+ *       required:
+ *         - item_id
+ *         - quantity
+ *       properties:
+ *         item_id:
+ *           description: The ID of the Line Item.
+ *           type: string
+ *         reason_id:
+ *           description: The ID of the Return Reason to use.
+ *           type: string
+ *         note:
+ *           description: An optional note with information about the Return.
+ *           type: string
+ *         quantity:
+ *           description: The quantity of the Line Item.
+ *           type: integer
+ *   return_shipping:
+ *     description: The Shipping Method to be used to handle the return shipment.
+ *     type: object
+ *     properties:
+ *       option_id:
+ *         type: string
+ *         description: The ID of the Shipping Option to create the Shipping Method from.
+ *       price:
+ *         type: integer
+ *         description: The price to charge for the Shipping Method.
+ *   note:
+ *     description: An optional note with information about the Return.
+ *     type: string
+ *   receive_now:
+ *     description: A flag to indicate if the Return should be registerd as received immediately.
+ *     type: boolean
+ *     default: false
+ *   no_notification:
+ *     description: A flag to indicate if no notifications should be emitted related to the requested Return.
+ *     type: boolean
+ *   refund:
+ *     description: The amount to refund.
+ *     type: integer
+ */
 export class AdminPostOrdersOrderReturnsReq {
   @IsArray()
   @ValidateNested({ each: true })

packages/medusa/src/api/routes/admin/orders/update-claim.ts

@@ -28,6 +28,85 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
+ *         $ref: "#/components/schemas/AdminPostOrdersOrderClaimsClaimReq"
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.orders.updateClaim(order_id, claim_id, {
+ *         no_notification: true
+ *       })
+ *       .then(({ order }) => {
+ *         console.log(order.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "no_notification": true
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
+ * tags:
+ *   - Claim
+ * responses:
+ *   200:
+ *     description: OK
+ *     content:
+ *       application/json:
+ *         schema:
+ *           type: object
+ *           properties:
+ *             order:
+ *               $ref: "#/components/schemas/Order"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
+ */
+export default async (req, res) => {
+  const { id, claim_id } = req.params
+
+  const validated = await validator(
+    AdminPostOrdersOrderClaimsClaimReq,
+    req.body
+  )
+
+  const orderService: OrderService = req.scope.resolve("orderService")
+  const claimService: ClaimService = req.scope.resolve("claimService")
+
+  const manager: EntityManager = req.scope.resolve("manager")
+  await manager.transaction(async (transactionManager) => {
+    return await claimService
+      .withTransaction(transactionManager)
+      .update(claim_id, validated)
+  })
+
+  const data = await orderService.retrieve(id, {
+    select: defaultAdminOrdersFields,
+    relations: defaultAdminOrdersRelations,
+  })
+
+  res.json({ order: data })
+}
+
+/**
+ * @schema AdminPostOrdersOrderClaimsClaimReq
  * type: object
  * properties:
  *   claim_items:
@@ -106,82 +185,7 @@ import { EntityManager } from "typeorm"
  *   metadata:
  *     description: An optional set of key-value pairs to hold additional information.
  *     type: object
- * x-codeSamples:
- *   - lang: JavaScript
- *     label: JS Client
- *     source: |
- *       import Medusa from "@medusajs/medusa-js"
- *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
- *       // must be previously logged in or use api token
- *       medusa.admin.orders.updateClaim(order_id, claim_id, {
- *         no_notification: true
- *       })
- *       .then(({ order }) => {
- *         console.log(order.id);
- *       });
- *   - lang: Shell
- *     label: cURL
- *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/orders/{id}/claims/{claim_id}' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
- *       --data-raw '{
- *           "no_notification": true
- *       }'
- * security:
- *   - api_token: []
- *   - cookie_auth: []
- * tags:
- *   - Claim
- * responses:
- *   200:
- *     description: OK
- *     content:
- *       application/json:
- *         schema:
- *           type: object
- *           properties:
- *             order:
- *               $ref: "#/components/schemas/Order"
- *   "400":
- *     $ref: "#/components/responses/400_error"
- *   "401":
- *     $ref: "#/components/responses/unauthorized"
- *   "404":
- *     $ref: "#/components/responses/not_found_error"
- *   "409":
- *     $ref: "#/components/responses/invalid_state_error"
- *   "422":
- *     $ref: "#/components/responses/invalid_request_error"
- *   "500":
- *     $ref: "#/components/responses/500_error"
  */
-export default async (req, res) => {
-  const { id, claim_id } = req.params
-
-  const validated = await validator(
-    AdminPostOrdersOrderClaimsClaimReq,
-    req.body
-  )
-
-  const orderService: OrderService = req.scope.resolve("orderService")
-  const claimService: ClaimService = req.scope.resolve("claimService")
-
-  const manager: EntityManager = req.scope.resolve("manager")
-  await manager.transaction(async (transactionManager) => {
-    return await claimService
-      .withTransaction(transactionManager)
-      .update(claim_id, validated)
-  })
-
-  const data = await orderService.retrieve(id, {
-    select: defaultAdminOrdersFields,
-    relations: defaultAdminOrdersRelations,
-  })
-
-  res.json({ order: data })
-}
-
 export class AdminPostOrdersOrderClaimsClaimReq {
   @IsArray()
   @IsOptional()

packages/medusa/src/api/routes/admin/orders/update-order.ts

@@ -28,69 +28,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostOrdersOrderReq"
- *         properties:
- *           email:
- *             description: the email for the order
- *             type: string
- *           billing_address:
- *             description: Billing address
- *             anyOf:
- *               - $ref: "#/components/schemas/AddressFields"
- *           shipping_address:
- *             description: Shipping address
- *             anyOf:
- *               - $ref: "#/components/schemas/AddressFields"
- *           items:
- *             description: The Line Items for the order
- *             type: array
- *             items:
- *               $ref: "#/components/schemas/LineItem"
- *           region:
- *             description: ID of the region where the order belongs
- *             type: string
- *           discounts:
- *             description: Discounts applied to the order
- *             type: array
- *             items:
- *               $ref: "#/components/schemas/Discount"
- *           customer_id:
- *             description: ID of the customer
- *             type: string
- *           payment_method:
- *             description: payment method chosen for the order
- *             type: object
- *             properties:
- *               provider_id:
- *                 type: string
- *                 description: ID of the payment provider
- *               data:
- *                 description: Data relevant for the given payment method
- *                 type: object
- *           shipping_method:
- *             description: The Shipping Method used for shipping the order.
- *             type: object
- *             properties:
- *               provider_id:
- *                 type: string
- *                 description: The ID of the shipping provider.
- *               profile_id:
- *                 type: string
- *                 description: The ID of the shipping profile.
- *               price:
- *                 type: integer
- *                 description: The price of the shipping.
- *               data:
- *                 type: object
- *                 description: Data relevant to the specific shipping method.
- *               items:
- *                 type: array
- *                 items:
- *                   $ref: "#/components/schemas/LineItem"
- *                 description: Items to ship
- *           no_notification:
- *             description: A flag to indicate if no notifications should be emitted related to the updated order.
- *             type: boolean
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -164,6 +102,72 @@ export default async (req, res) => {
   res.status(200).json({ order })
 }
 
+/**
+ * @schema AdminPostOrdersOrderReq
+ * type: object
+ * properties:
+ *   email:
+ *     description: the email for the order
+ *     type: string
+ *   billing_address:
+ *     description: Billing address
+ *     anyOf:
+ *       - $ref: "#/components/schemas/AddressFields"
+ *   shipping_address:
+ *     description: Shipping address
+ *     anyOf:
+ *       - $ref: "#/components/schemas/AddressFields"
+ *   items:
+ *     description: The Line Items for the order
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/LineItem"
+ *   region:
+ *     description: ID of the region where the order belongs
+ *     type: string
+ *   discounts:
+ *     description: Discounts applied to the order
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/Discount"
+ *   customer_id:
+ *     description: ID of the customer
+ *     type: string
+ *   payment_method:
+ *     description: payment method chosen for the order
+ *     type: object
+ *     properties:
+ *       provider_id:
+ *         type: string
+ *         description: ID of the payment provider
+ *       data:
+ *         description: Data relevant for the given payment method
+ *         type: object
+ *   shipping_method:
+ *     description: The Shipping Method used for shipping the order.
+ *     type: object
+ *     properties:
+ *       provider_id:
+ *         type: string
+ *         description: The ID of the shipping provider.
+ *       profile_id:
+ *         type: string
+ *         description: The ID of the shipping profile.
+ *       price:
+ *         type: integer
+ *         description: The price of the shipping.
+ *       data:
+ *         type: object
+ *         description: Data relevant to the specific shipping method.
+ *       items:
+ *         type: array
+ *         items:
+ *           $ref: "#/components/schemas/LineItem"
+ *         description: Items to ship
+ *   no_notification:
+ *     description: A flag to indicate if no notifications should be emitted related to the updated order.
+ *     type: boolean
+ */
 export class AdminPostOrdersOrderReq {
   @IsEmail()
   @IsOptional()

packages/medusa/src/api/routes/admin/payment-collections/update-payment-collection.ts

@@ -15,14 +15,7 @@ import { PaymentCollectionService } from "../../../../services"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminUpdatePaymentCollectionsReq"
- *         properties:
- *           description:
- *             description: An optional description to create or update the payment collection.
- *             type: string
- *           metadata:
- *             description: An optional set of key-value pairs to hold additional information.
- *             type: object
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -93,6 +86,17 @@ export default async (req, res) => {
   res.status(200).json({ payment_collection: paymentCollection })
 }
 
+/**
+ * @schema AdminUpdatePaymentCollectionsReq
+ * type: object
+ * properties:
+ *   description:
+ *     description: An optional description to create or update the payment collection.
+ *     type: string
+ *   metadata:
+ *     description: An optional set of key-value pairs to hold additional information.
+ *     type: object
+ */
 export class AdminUpdatePaymentCollectionsReq {
   @IsString()
   @IsOptional()

packages/medusa/src/api/routes/admin/payments/refund-payment.ts

@@ -21,20 +21,7 @@ import { PaymentService } from "../../../../services"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostPaymentRefundsReq"
- *         required:
- *           - amount
- *           - reason
- *         properties:
- *           amount:
- *             description: The amount to refund.
- *             type: integer
- *           reason:
- *             description: The reason for the Refund.
- *             type: string
- *           note:
- *             description: A note with additional details about the Refund.
- *             type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -106,6 +93,23 @@ export default async (req, res) => {
   res.status(200).json({ refund })
 }
 
+/**
+ * @schema AdminPostPaymentRefundsReq
+ * type: object
+ * required:
+ *   - amount
+ *   - reason
+ * properties:
+ *   amount:
+ *     description: The amount to refund.
+ *     type: integer
+ *   reason:
+ *     description: The reason for the Refund.
+ *     type: string
+ *   note:
+ *     description: A note with additional details about the Refund.
+ *     type: string
+ */
 export class AdminPostPaymentRefundsReq {
   @IsInt()
   @IsNotEmpty()

packages/medusa/src/api/routes/admin/price-lists/add-prices-batch.ts

@@ -20,43 +20,7 @@ import { EntityManager } from "typeorm"
  *  content:
  *    application/json:
  *      schema:
- *        type: object
+ *        $ref: "#/components/schemas/AdminPostPriceListPricesPricesReq"
- *        properties:
- *          prices:
- *            description: The prices to update or add.
- *            type: array
- *            items:
- *              required:
- *                - amount
- *                - variant_id
- *              properties:
- *                id:
- *                  description: The ID of the price.
- *                  type: string
- *                region_id:
- *                  description: The ID of the Region for which the price is used. Only required if currecny_code is not provided.
- *                  type: string
- *                currency_code:
- *                  description: The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided.
- *                  type: string
- *                  externalDocs:
- *                    url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
- *                    description: See a list of codes.
- *                variant_id:
- *                  description: The ID of the Variant for which the price is used.
- *                  type: string
- *                amount:
- *                  description: The amount to charge for the Product Variant.
- *                  type: integer
- *                min_quantity:
- *                  description: The minimum quantity for which the price will be used.
- *                  type: integer
- *                max_quantity:
- *                  description: The maximum quantity for which the price will be used.
- *                  type: integer
- *          override:
- *            description: "If true the prices will replace all existing prices associated with the Price List."
- *            type: boolean
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -142,6 +106,46 @@ export default async (req, res) => {
   res.json({ price_list: priceList })
 }
 
+/**
+ * @schema AdminPostPriceListPricesPricesReq
+ * type: object
+ * properties:
+ *   prices:
+ *     description: The prices to update or add.
+ *     type: array
+ *     items:
+ *       required:
+ *         - amount
+ *         - variant_id
+ *       properties:
+ *         id:
+ *           description: The ID of the price.
+ *           type: string
+ *         region_id:
+ *           description: The ID of the Region for which the price is used. Only required if currecny_code is not provided.
+ *           type: string
+ *         currency_code:
+ *           description: The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided.
+ *           type: string
+ *           externalDocs:
+ *             url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+ *             description: See a list of codes.
+ *         variant_id:
+ *           description: The ID of the Variant for which the price is used.
+ *           type: string
+ *         amount:
+ *           description: The amount to charge for the Product Variant.
+ *           type: integer
+ *         min_quantity:
+ *           description: The minimum quantity for which the price will be used.
+ *           type: integer
+ *         max_quantity:
+ *           description: The maximum quantity for which the price will be used.
+ *           type: integer
+ *   override:
+ *     description: "If true the prices will replace all existing prices associated with the Price List."
+ *     type: boolean
+ */
 export class AdminPostPriceListPricesPricesReq {
   @IsArray()
   @Type(() => AdminPriceListPricesUpdateReq)

packages/medusa/src/api/routes/admin/price-lists/create-price-list.ts

@@ -30,81 +30,7 @@ import { FeatureFlagDecorators } from "../../../../utils/feature-flag-decorators
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostPriceListsPriceListReq"
- *         required:
- *           - name
- *           - description
- *           - type
- *           - prices
- *         properties:
- *           name:
- *             description: "The name of the Price List"
- *             type: string
- *           description:
- *             description: "A description of the Price List."
- *             type: string
- *           starts_at:
- *             description: "The date with timezone that the Price List starts being valid."
- *             type: string
- *             format: date
- *           ends_at:
- *             description: "The date with timezone that the Price List ends being valid."
- *             type: string
- *             format: date
- *           type:
- *             description: The type of the Price List.
- *             type: string
- *             enum:
- *              - sale
- *              - override
- *           status:
- *             description: The status of the Price List.
- *             type: string
- *             enum:
- *               - active
- *               - draft
- *           prices:
- *              description: The prices of the Price List.
- *              type: array
- *              items:
- *                required:
- *                  - amount
- *                  - variant_id
- *                properties:
- *                  region_id:
- *                    description: The ID of the Region for which the price is used. Only required if currecny_code is not provided.
- *                    type: string
- *                  currency_code:
- *                    description: The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided.
- *                    type: string
- *                    externalDocs:
- *                      url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
- *                      description: See a list of codes.
- *                  amount:
- *                    description: The amount to charge for the Product Variant.
- *                    type: integer
- *                  variant_id:
- *                    description: The ID of the Variant for which the price is used.
- *                    type: string
- *                  min_quantity:
- *                    description: The minimum quantity for which the price will be used.
- *                    type: integer
- *                  max_quantity:
- *                    description: The maximum quantity for which the price will be used.
- *                    type: integer
- *           customer_groups:
- *             type: array
- *             description: A list of customer groups that the Price List applies to.
- *             items:
- *               required:
- *                 - id
- *               properties:
- *                 id:
- *                   description: The ID of a customer group
- *                   type: string
- *           includes_tax:
- *              description: "[EXPERIMENTAL] Tax included in prices of price list"
- *              type: boolean
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -193,6 +119,84 @@ class CustomerGroup {
   id: string
 }
 
+/**
+ * @schema AdminPostPriceListsPriceListReq
+ * type: object
+ * required:
+ *   - name
+ *   - description
+ *   - type
+ *   - prices
+ * properties:
+ *   name:
+ *     description: "The name of the Price List"
+ *     type: string
+ *   description:
+ *     description: "A description of the Price List."
+ *     type: string
+ *   starts_at:
+ *     description: "The date with timezone that the Price List starts being valid."
+ *     type: string
+ *     format: date
+ *   ends_at:
+ *     description: "The date with timezone that the Price List ends being valid."
+ *     type: string
+ *     format: date
+ *   type:
+ *     description: The type of the Price List.
+ *     type: string
+ *     enum:
+ *      - sale
+ *      - override
+ *   status:
+ *     description: The status of the Price List.
+ *     type: string
+ *     enum:
+ *       - active
+ *       - draft
+ *   prices:
+ *      description: The prices of the Price List.
+ *      type: array
+ *      items:
+ *        required:
+ *          - amount
+ *          - variant_id
+ *        properties:
+ *          region_id:
+ *            description: The ID of the Region for which the price is used. Only required if currecny_code is not provided.
+ *            type: string
+ *          currency_code:
+ *            description: The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided.
+ *            type: string
+ *            externalDocs:
+ *              url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+ *              description: See a list of codes.
+ *          amount:
+ *            description: The amount to charge for the Product Variant.
+ *            type: integer
+ *          variant_id:
+ *            description: The ID of the Variant for which the price is used.
+ *            type: string
+ *          min_quantity:
+ *            description: The minimum quantity for which the price will be used.
+ *            type: integer
+ *          max_quantity:
+ *            description: The maximum quantity for which the price will be used.
+ *            type: integer
+ *   customer_groups:
+ *     type: array
+ *     description: A list of customer groups that the Price List applies to.
+ *     items:
+ *       required:
+ *         - id
+ *       properties:
+ *         id:
+ *           description: The ID of a customer group
+ *           type: string
+ *   includes_tax:
+ *      description: "[EXPERIMENTAL] Tax included in prices of price list"
+ *      type: boolean
+ */
 export class AdminPostPriceListsPriceListReq {
   @IsString()
   name: string

packages/medusa/src/api/routes/admin/price-lists/delete-prices-batch.ts

@@ -16,13 +16,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminDeletePriceListPricesPricesReq"
- *         properties:
- *           price_ids:
- *             description: The price id's of the Money Amounts to delete.
- *             type: array
- *             items:
- *               type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -109,6 +103,16 @@ export default async (req, res) => {
   res.json({ ids: validated.price_ids, object: "money-amount", deleted: true })
 }
 
+/**
+ * @schema AdminDeletePriceListPricesPricesReq
+ * type: object
+ * properties:
+ *   price_ids:
+ *     description: The price id's of the Money Amounts to delete.
+ *     type: array
+ *     items:
+ *       type: string
+ */
 export class AdminDeletePriceListPricesPricesReq {
   @ArrayNotEmpty()
   @IsString({ each: true })

packages/medusa/src/api/routes/admin/price-lists/update-price-list.ts

@@ -33,79 +33,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostPriceListsPriceListPriceListReq"
- *         properties:
- *           name:
- *             description: "The name of the Price List"
- *             type: string
- *           description:
- *             description: "A description of the Price List."
- *             type: string
- *           starts_at:
- *             description: "The date with timezone that the Price List starts being valid."
- *             type: string
- *             format: date
- *           ends_at:
- *             description: "The date with timezone that the Price List ends being valid."
- *             type: string
- *             format: date
- *           type:
- *             description: The type of the Price List.
- *             type: string
- *             enum:
- *              - sale
- *              - override
- *           status:
- *             description: The status of the Price List.
- *             type: string
- *             enum:
- *              - active
- *              - draft
- *           prices:
- *             description: The prices of the Price List.
- *             type: array
- *             items:
- *               required:
- *                 - amount
- *                 - variant_id
- *               properties:
- *                 id:
- *                   description: The ID of the price.
- *                   type: string
- *                 region_id:
- *                   description: The ID of the Region for which the price is used. Only required if currecny_code is not provided.
- *                   type: string
- *                 currency_code:
- *                   description: The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided.
- *                   type: string
- *                   externalDocs:
- *                      url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
- *                      description: See a list of codes.
- *                 variant_id:
- *                   description: The ID of the Variant for which the price is used.
- *                   type: string
- *                 amount:
- *                   description: The amount to charge for the Product Variant.
- *                   type: integer
- *                 min_quantity:
- *                   description: The minimum quantity for which the price will be used.
- *                   type: integer
- *                 max_quantity:
- *                   description: The maximum quantity for which the price will be used.
- *                   type: integer
- *           customer_groups:
- *             type: array
- *             description: A list of customer groups that the Price List applies to.
- *             items:
- *               required:
- *                 - id
- *               properties:
- *                 id:
- *                   description: The ID of a customer group
- *                   type: string
- *           includes_tax:
- *             description: "[EXPERIMENTAL] Tax included in prices of price list"
- *             type: boolean
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -187,6 +115,82 @@ class CustomerGroup {
   id: string
 }
 
+/**
+ * @schema AdminPostPriceListsPriceListPriceListReq
+ * type: object
+ * properties:
+ *   name:
+ *     description: "The name of the Price List"
+ *     type: string
+ *   description:
+ *     description: "A description of the Price List."
+ *     type: string
+ *   starts_at:
+ *     description: "The date with timezone that the Price List starts being valid."
+ *     type: string
+ *     format: date
+ *   ends_at:
+ *     description: "The date with timezone that the Price List ends being valid."
+ *     type: string
+ *     format: date
+ *   type:
+ *     description: The type of the Price List.
+ *     type: string
+ *     enum:
+ *      - sale
+ *      - override
+ *   status:
+ *     description: The status of the Price List.
+ *     type: string
+ *     enum:
+ *      - active
+ *      - draft
+ *   prices:
+ *     description: The prices of the Price List.
+ *     type: array
+ *     items:
+ *       required:
+ *         - amount
+ *         - variant_id
+ *       properties:
+ *         id:
+ *           description: The ID of the price.
+ *           type: string
+ *         region_id:
+ *           description: The ID of the Region for which the price is used. Only required if currecny_code is not provided.
+ *           type: string
+ *         currency_code:
+ *           description: The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided.
+ *           type: string
+ *           externalDocs:
+ *              url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+ *              description: See a list of codes.
+ *         variant_id:
+ *           description: The ID of the Variant for which the price is used.
+ *           type: string
+ *         amount:
+ *           description: The amount to charge for the Product Variant.
+ *           type: integer
+ *         min_quantity:
+ *           description: The minimum quantity for which the price will be used.
+ *           type: integer
+ *         max_quantity:
+ *           description: The maximum quantity for which the price will be used.
+ *           type: integer
+ *   customer_groups:
+ *     type: array
+ *     description: A list of customer groups that the Price List applies to.
+ *     items:
+ *       required:
+ *         - id
+ *       properties:
+ *         id:
+ *           description: The ID of a customer group
+ *           type: string
+ *   includes_tax:
+ *     description: "[EXPERIMENTAL] Tax included in prices of price list"
+ *     type: boolean
+ */
 export class AdminPostPriceListsPriceListPriceListReq {
   @IsString()
   @IsOptional()

packages/medusa/src/api/routes/admin/products/add-option.ts

@@ -17,13 +17,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostProductsProductOptionsReq"
- *         required:
- *           - title
- *         properties:
- *           title:
- *             description: "The title the Product Option will be identified by i.e. \"Size\""
- *             type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -102,6 +96,16 @@ export default async (req, res) => {
   res.json({ product })
 }
 
+/**
+ * @schema AdminPostProductsProductOptionsReq
+ * type: object
+ * required:
+ *   - title
+ * properties:
+ *   title:
+ *     description: "The title the Product Option will be identified by i.e. \"Size\""
+ *     type: string
+ */
 export class AdminPostProductsProductOptionsReq {
   @IsString()
   title: string

packages/medusa/src/api/routes/admin/products/create-product.ts

@@ -42,210 +42,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostProductsReq"
- *         required:
- *           - title
- *         properties:
- *           title:
- *             description: "The title of the Product"
- *             type: string
- *           subtitle:
- *             description: "The subtitle of the Product"
- *             type: string
- *           description:
- *             description: "A description of the Product."
- *             type: string
- *           is_giftcard:
- *             description: A flag to indicate if the Product represents a Gift Card. Purchasing Products with this flag set to `true` will result in a Gift Card being created.
- *             type: boolean
- *             default: false
- *           discountable:
- *             description: A flag to indicate if discounts can be applied to the LineItems generated from this Product
- *             type: boolean
- *             default: true
- *           images:
- *             description: Images of the Product.
- *             type: array
- *             items:
- *               type: string
- *           thumbnail:
- *             description: The thumbnail to use for the Product.
- *             type: string
- *           handle:
- *             description: A unique handle to identify the Product by.
- *             type: string
- *           status:
- *             description: The status of the product.
- *             type: string
- *             enum: [draft, proposed, published, rejected]
- *             default: draft
- *           type:
- *             description: The Product Type to associate the Product with.
- *             type: object
- *             required:
- *               - value
- *             properties:
- *               id:
- *                 description: The ID of the Product Type.
- *                 type: string
- *               value:
- *                 description: The value of the Product Type.
- *                 type: string
- *           collection_id:
- *             description: The ID of the Collection the Product should belong to.
- *             type: string
- *           tags:
- *             description: Tags to associate the Product with.
- *             type: array
- *             items:
- *               required:
- *                 - value
- *               properties:
- *                 id:
- *                   description: The ID of an existing Tag.
- *                   type: string
- *                 value:
- *                   description: The value of the Tag, these will be upserted.
- *                   type: string
- *           sales_channels:
- *             description: "[EXPERIMENTAL] Sales channels to associate the Product with."
- *             type: array
- *             items:
- *               required:
- *                 - id
- *               properties:
- *                 id:
- *                   description: The ID of an existing Sales channel.
- *                   type: string
- *           options:
- *             description: The Options that the Product should have. These define on which properties the Product's Product Variants will differ.
- *             type: array
- *             items:
- *               required:
- *                 - title
- *               properties:
- *                 title:
- *                   description: The title to identify the Product Option by.
- *                   type: string
- *           variants:
- *             description: A list of Product Variants to create with the Product.
- *             type: array
- *             items:
- *               required:
- *                 - title
- *               properties:
- *                 title:
- *                   description: The title to identify the Product Variant by.
- *                   type: string
- *                 sku:
- *                   description: The unique SKU for the Product Variant.
- *                   type: string
- *                 ean:
- *                   description: The EAN number of the item.
- *                   type: string
- *                 upc:
- *                   description: The UPC number of the item.
- *                   type: string
- *                 barcode:
- *                   description: A generic GTIN field for the Product Variant.
- *                   type: string
- *                 hs_code:
- *                   description: The Harmonized System code for the Product Variant.
- *                   type: string
- *                 inventory_quantity:
- *                   description: The amount of stock kept for the Product Variant.
- *                   type: integer
- *                   default: 0
- *                 allow_backorder:
- *                   description: Whether the Product Variant can be purchased when out of stock.
- *                   type: boolean
- *                 manage_inventory:
- *                   description: Whether Medusa should keep track of the inventory for this Product Variant.
- *                   type: boolean
- *                 weight:
- *                   description: The wieght of the Product Variant.
- *                   type: number
- *                 length:
- *                   description: The length of the Product Variant.
- *                   type: number
- *                 height:
- *                   description: The height of the Product Variant.
- *                   type: number
- *                 width:
- *                   description: The width of the Product Variant.
- *                   type: number
- *                 origin_country:
- *                   description: The country of origin of the Product Variant.
- *                   type: string
- *                 mid_code:
- *                   description: The Manufacturer Identification code for the Product Variant.
- *                   type: string
- *                 material:
- *                   description: The material composition of the Product Variant.
- *                   type: string
- *                 metadata:
- *                   description: An optional set of key-value pairs with additional information.
- *                   type: object
- *                 prices:
- *                   type: array
- *                   items:
- *                     required:
- *                       - amount
- *                     properties:
- *                       region_id:
- *                         description: The ID of the Region for which the price is used. Only required if currency_code is not provided.
- *                         type: string
- *                       currency_code:
- *                         description: The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided.
- *                         type: string
- *                         externalDocs:
- *                           url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
- *                           description: See a list of codes.
- *                       amount:
- *                         description: The amount to charge for the Product Variant.
- *                         type: integer
- *                       min_quantity:
- *                         description: The minimum quantity for which the price will be used.
- *                         type: integer
- *                       max_quantity:
- *                         description: The maximum quantity for which the price will be used.
- *                         type: integer
- *                 options:
- *                   type: array
- *                   items:
- *                     required:
- *                       - value
- *                     properties:
- *                       value:
- *                         description: The value to give for the Product Option at the same index in the Product's `options` field.
- *                         type: string
- *           weight:
- *             description: The weight of the Product.
- *             type: number
- *           length:
- *             description: The length of the Product.
- *             type: number
- *           height:
- *             description: The height of the Product.
- *             type: number
- *           width:
- *             description: The width of the Product.
- *             type: number
- *           hs_code:
- *             description: The Harmonized System code for the Product Variant.
- *             type: string
- *           origin_country:
- *             description: The country of origin of the Product.
- *             type: string
- *           mid_code:
- *             description: The Manufacturer Identification code for the Product.
- *             type: string
- *           material:
- *             description: The material composition of the Product.
- *             type: string
- *           metadata:
- *             description: An optional set of key-value pairs with additional information.
- *             type: object
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -467,6 +264,213 @@ class ProductVariantReq {
   options?: ProductVariantOptionReq[] = []
 }
 
+/**
+ * @schema AdminPostProductsReq
+ * type: object
+ * required:
+ *   - title
+ * properties:
+ *   title:
+ *     description: "The title of the Product"
+ *     type: string
+ *   subtitle:
+ *     description: "The subtitle of the Product"
+ *     type: string
+ *   description:
+ *     description: "A description of the Product."
+ *     type: string
+ *   is_giftcard:
+ *     description: A flag to indicate if the Product represents a Gift Card. Purchasing Products with this flag set to `true` will result in a Gift Card being created.
+ *     type: boolean
+ *     default: false
+ *   discountable:
+ *     description: A flag to indicate if discounts can be applied to the LineItems generated from this Product
+ *     type: boolean
+ *     default: true
+ *   images:
+ *     description: Images of the Product.
+ *     type: array
+ *     items:
+ *       type: string
+ *   thumbnail:
+ *     description: The thumbnail to use for the Product.
+ *     type: string
+ *   handle:
+ *     description: A unique handle to identify the Product by.
+ *     type: string
+ *   status:
+ *     description: The status of the product.
+ *     type: string
+ *     enum: [draft, proposed, published, rejected]
+ *     default: draft
+ *   type:
+ *     description: The Product Type to associate the Product with.
+ *     type: object
+ *     required:
+ *       - value
+ *     properties:
+ *       id:
+ *         description: The ID of the Product Type.
+ *         type: string
+ *       value:
+ *         description: The value of the Product Type.
+ *         type: string
+ *   collection_id:
+ *     description: The ID of the Collection the Product should belong to.
+ *     type: string
+ *   tags:
+ *     description: Tags to associate the Product with.
+ *     type: array
+ *     items:
+ *       required:
+ *         - value
+ *       properties:
+ *         id:
+ *           description: The ID of an existing Tag.
+ *           type: string
+ *         value:
+ *           description: The value of the Tag, these will be upserted.
+ *           type: string
+ *   sales_channels:
+ *     description: "[EXPERIMENTAL] Sales channels to associate the Product with."
+ *     type: array
+ *     items:
+ *       required:
+ *         - id
+ *       properties:
+ *         id:
+ *           description: The ID of an existing Sales channel.
+ *           type: string
+ *   options:
+ *     description: The Options that the Product should have. These define on which properties the Product's Product Variants will differ.
+ *     type: array
+ *     items:
+ *       required:
+ *         - title
+ *       properties:
+ *         title:
+ *           description: The title to identify the Product Option by.
+ *           type: string
+ *   variants:
+ *     description: A list of Product Variants to create with the Product.
+ *     type: array
+ *     items:
+ *       required:
+ *         - title
+ *       properties:
+ *         title:
+ *           description: The title to identify the Product Variant by.
+ *           type: string
+ *         sku:
+ *           description: The unique SKU for the Product Variant.
+ *           type: string
+ *         ean:
+ *           description: The EAN number of the item.
+ *           type: string
+ *         upc:
+ *           description: The UPC number of the item.
+ *           type: string
+ *         barcode:
+ *           description: A generic GTIN field for the Product Variant.
+ *           type: string
+ *         hs_code:
+ *           description: The Harmonized System code for the Product Variant.
+ *           type: string
+ *         inventory_quantity:
+ *           description: The amount of stock kept for the Product Variant.
+ *           type: integer
+ *           default: 0
+ *         allow_backorder:
+ *           description: Whether the Product Variant can be purchased when out of stock.
+ *           type: boolean
+ *         manage_inventory:
+ *           description: Whether Medusa should keep track of the inventory for this Product Variant.
+ *           type: boolean
+ *         weight:
+ *           description: The wieght of the Product Variant.
+ *           type: number
+ *         length:
+ *           description: The length of the Product Variant.
+ *           type: number
+ *         height:
+ *           description: The height of the Product Variant.
+ *           type: number
+ *         width:
+ *           description: The width of the Product Variant.
+ *           type: number
+ *         origin_country:
+ *           description: The country of origin of the Product Variant.
+ *           type: string
+ *         mid_code:
+ *           description: The Manufacturer Identification code for the Product Variant.
+ *           type: string
+ *         material:
+ *           description: The material composition of the Product Variant.
+ *           type: string
+ *         metadata:
+ *           description: An optional set of key-value pairs with additional information.
+ *           type: object
+ *         prices:
+ *           type: array
+ *           items:
+ *             required:
+ *               - amount
+ *             properties:
+ *               region_id:
+ *                 description: The ID of the Region for which the price is used. Only required if currency_code is not provided.
+ *                 type: string
+ *               currency_code:
+ *                 description: The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided.
+ *                 type: string
+ *                 externalDocs:
+ *                   url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+ *                   description: See a list of codes.
+ *               amount:
+ *                 description: The amount to charge for the Product Variant.
+ *                 type: integer
+ *               min_quantity:
+ *                 description: The minimum quantity for which the price will be used.
+ *                 type: integer
+ *               max_quantity:
+ *                 description: The maximum quantity for which the price will be used.
+ *                 type: integer
+ *         options:
+ *           type: array
+ *           items:
+ *             required:
+ *               - value
+ *             properties:
+ *               value:
+ *                 description: The value to give for the Product Option at the same index in the Product's `options` field.
+ *                 type: string
+ *   weight:
+ *     description: The weight of the Product.
+ *     type: number
+ *   length:
+ *     description: The length of the Product.
+ *     type: number
+ *   height:
+ *     description: The height of the Product.
+ *     type: number
+ *   width:
+ *     description: The width of the Product.
+ *     type: number
+ *   hs_code:
+ *     description: The Harmonized System code for the Product Variant.
+ *     type: string
+ *   origin_country:
+ *     description: The country of origin of the Product.
+ *     type: string
+ *   mid_code:
+ *     description: The Manufacturer Identification code for the Product.
+ *     type: string
+ *   material:
+ *     description: The material composition of the Product.
+ *     type: string
+ *   metadata:
+ *     description: An optional set of key-value pairs with additional information.
+ *     type: object
+ */
 export class AdminPostProductsReq {
   @IsString()
   title: string

packages/medusa/src/api/routes/admin/products/create-variant.ts

@@ -30,104 +30,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostProductsProductVariantsReq"
- *         required:
- *           - title
- *           - prices
- *           - options
- *         properties:
- *           title:
- *             description: The title to identify the Product Variant by.
- *             type: string
- *           sku:
- *             description: The unique SKU for the Product Variant.
- *             type: string
- *           ean:
- *             description: The EAN number of the item.
- *             type: string
- *           upc:
- *             description: The UPC number of the item.
- *             type: string
- *           barcode:
- *             description: A generic GTIN field for the Product Variant.
- *             type: string
- *           hs_code:
- *             description: The Harmonized System code for the Product Variant.
- *             type: string
- *           inventory_quantity:
- *             description: The amount of stock kept for the Product Variant.
- *             type: integer
- *             default: 0
- *           allow_backorder:
- *             description: Whether the Product Variant can be purchased when out of stock.
- *             type: boolean
- *           manage_inventory:
- *             description: Whether Medusa should keep track of the inventory for this Product Variant.
- *             type: boolean
- *           weight:
- *             description: The wieght of the Product Variant.
- *             type: number
- *           length:
- *             description: The length of the Product Variant.
- *             type: number
- *           height:
- *             description: The height of the Product Variant.
- *             type: number
- *           width:
- *             description: The width of the Product Variant.
- *             type: number
- *           origin_country:
- *             description: The country of origin of the Product Variant.
- *             type: string
- *           mid_code:
- *             description: The Manufacturer Identification code for the Product Variant.
- *             type: string
- *           material:
- *             description: The material composition of the Product Variant.
- *             type: string
- *           metadata:
- *             description: An optional set of key-value pairs with additional information.
- *             type: object
- *           prices:
- *             type: array
- *             items:
- *               required:
- *                 - amount
- *               properties:
- *                 id:
- *                   description: The ID of the price.
- *                   type: string
- *                 region_id:
- *                   description: The ID of the Region for which the price is used. Only required if currency_code is not provided.
- *                   type: string
- *                 currency_code:
- *                   description: The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided.
- *                   type: string
- *                   externalDocs:
- *                     url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
- *                     description: See a list of codes.
- *                 amount:
- *                   description: The amount to charge for the Product Variant.
- *                   type: integer
- *                 min_quantity:
- *                  description: The minimum quantity for which the price will be used.
- *                  type: integer
- *                 max_quantity:
- *                   description: The maximum quantity for which the price will be used.
- *                   type: integer
- *           options:
- *             type: array
- *             items:
- *               required:
- *                 - option_id
- *                 - value
- *               properties:
- *                 option_id:
- *                   description: The ID of the Product Option to set the value for.
- *                   type: string
- *                 value:
- *                   description: The value to give for the Product Option.
- *                   type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -239,6 +142,107 @@ class ProductVariantOptionReq {
   option_id: string
 }
 
+/**
+ * @schema AdminPostProductsProductVariantsReq
+ * type: object
+ * required:
+ *   - title
+ *   - prices
+ *   - options
+ * properties:
+ *   title:
+ *     description: The title to identify the Product Variant by.
+ *     type: string
+ *   sku:
+ *     description: The unique SKU for the Product Variant.
+ *     type: string
+ *   ean:
+ *     description: The EAN number of the item.
+ *     type: string
+ *   upc:
+ *     description: The UPC number of the item.
+ *     type: string
+ *   barcode:
+ *     description: A generic GTIN field for the Product Variant.
+ *     type: string
+ *   hs_code:
+ *     description: The Harmonized System code for the Product Variant.
+ *     type: string
+ *   inventory_quantity:
+ *     description: The amount of stock kept for the Product Variant.
+ *     type: integer
+ *     default: 0
+ *   allow_backorder:
+ *     description: Whether the Product Variant can be purchased when out of stock.
+ *     type: boolean
+ *   manage_inventory:
+ *     description: Whether Medusa should keep track of the inventory for this Product Variant.
+ *     type: boolean
+ *   weight:
+ *     description: The wieght of the Product Variant.
+ *     type: number
+ *   length:
+ *     description: The length of the Product Variant.
+ *     type: number
+ *   height:
+ *     description: The height of the Product Variant.
+ *     type: number
+ *   width:
+ *     description: The width of the Product Variant.
+ *     type: number
+ *   origin_country:
+ *     description: The country of origin of the Product Variant.
+ *     type: string
+ *   mid_code:
+ *     description: The Manufacturer Identification code for the Product Variant.
+ *     type: string
+ *   material:
+ *     description: The material composition of the Product Variant.
+ *     type: string
+ *   metadata:
+ *     description: An optional set of key-value pairs with additional information.
+ *     type: object
+ *   prices:
+ *     type: array
+ *     items:
+ *       required:
+ *         - amount
+ *       properties:
+ *         id:
+ *           description: The ID of the price.
+ *           type: string
+ *         region_id:
+ *           description: The ID of the Region for which the price is used. Only required if currency_code is not provided.
+ *           type: string
+ *         currency_code:
+ *           description: The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided.
+ *           type: string
+ *           externalDocs:
+ *             url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+ *             description: See a list of codes.
+ *         amount:
+ *           description: The amount to charge for the Product Variant.
+ *           type: integer
+ *         min_quantity:
+ *          description: The minimum quantity for which the price will be used.
+ *          type: integer
+ *         max_quantity:
+ *           description: The maximum quantity for which the price will be used.
+ *           type: integer
+ *   options:
+ *     type: array
+ *     items:
+ *       required:
+ *         - option_id
+ *         - value
+ *       properties:
+ *         option_id:
+ *           description: The ID of the Product Option to set the value for.
+ *           type: string
+ *         value:
+ *           description: The value to give for the Product Option.
+ *           type: string
+ */
 export class AdminPostProductsProductVariantsReq {
   @IsString()
   title: string

packages/medusa/src/api/routes/admin/products/set-metadata.ts

@@ -16,17 +16,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostProductsProductMetadataReq"
- *         required:
- *           - key
- *           - value
- *         properties:
- *           key:
- *             description: The metadata key
- *             type: string
- *           value:
- *             description: The metadata value
- *             type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -103,6 +93,20 @@ export default async (req, res) => {
   res.status(200).json({ product })
 }
 
+/**
+ * @schema AdminPostProductsProductMetadataReq
+ * type: object
+ * required:
+ *   - key
+ *   - value
+ * properties:
+ *   key:
+ *     description: The metadata key
+ *     type: string
+ *   value:
+ *     description: The metadata value
+ *     type: string
+ */
 export class AdminPostProductsProductMetadataReq {
   @IsString()
   key: string

packages/medusa/src/api/routes/admin/products/update-option.ts

@@ -18,13 +18,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostProductsProductOptionsOption"
- *         required:
- *           - title
- *         properties:
- *           title:
- *             description: "The title of the Product Option"
- *             type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -100,6 +94,16 @@ export default async (req, res) => {
   res.json({ product })
 }
 
+/**
+ * @schema AdminPostProductsProductOptionsOption
+ * type: object
+ * required:
+ *   - title
+ * properties:
+ *   title:
+ *     description: "The title of the Product Option"
+ *     type: string
+ */
 export class AdminPostProductsProductOptionsOption {
   @IsString()
   title: string

packages/medusa/src/api/routes/admin/products/update-product.ts

@@ -39,6 +39,179 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
+ *         $ref: "#/components/schemas/AdminPostProductsProductReq"
+ * x-codeSamples:
+ *   - lang: JavaScript
+ *     label: JS Client
+ *     source: |
+ *       import Medusa from "@medusajs/medusa-js"
+ *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
+ *       // must be previously logged in or use api token
+ *       medusa.admin.products.update(product_id, {
+ *         title: 'Shirt',
+ *         images: []
+ *       })
+ *       .then(({ product }) => {
+ *         console.log(product.id);
+ *       });
+ *   - lang: Shell
+ *     label: cURL
+ *     source: |
+ *       curl --location --request POST 'https://medusa-url.com/admin/products/{id}' \
+ *       --header 'Authorization: Bearer {api_token}' \
+ *       --header 'Content-Type: application/json' \
+ *       --data-raw '{
+ *           "title": "Size"
+ *       }'
+ * security:
+ *   - api_token: []
+ *   - cookie_auth: []
+ * tags:
+ *   - Product
+ * responses:
+ *   200:
+ *     description: OK
+ *     content:
+ *       application/json:
+ *         schema:
+ *           type: object
+ *           properties:
+ *             product:
+ *               $ref: "#/components/schemas/Product"
+ *   "400":
+ *     $ref: "#/components/responses/400_error"
+ *   "401":
+ *     $ref: "#/components/responses/unauthorized"
+ *   "404":
+ *     $ref: "#/components/responses/not_found_error"
+ *   "409":
+ *     $ref: "#/components/responses/invalid_state_error"
+ *   "422":
+ *     $ref: "#/components/responses/invalid_request_error"
+ *   "500":
+ *     $ref: "#/components/responses/500_error"
+ */
+export default async (req, res) => {
+  const { id } = req.params
+
+  const validated = await validator(AdminPostProductsProductReq, req.body)
+
+  const productService: ProductService = req.scope.resolve("productService")
+  const pricingService: PricingService = req.scope.resolve("pricingService")
+
+  const manager: EntityManager = req.scope.resolve("manager")
+  await manager.transaction(async (transactionManager) => {
+    await productService
+      .withTransaction(transactionManager)
+      .update(id, validated)
+  })
+
+  const rawProduct = await productService.retrieve(id, {
+    select: defaultAdminProductFields,
+    relations: defaultAdminProductRelations,
+  })
+
+  const [product] = await pricingService.setProductPrices([rawProduct])
+
+  res.json({ product })
+}
+
+class ProductVariantOptionReq {
+  @IsString()
+  value: string
+
+  @IsString()
+  option_id: string
+}
+
+class ProductVariantReq {
+  @IsString()
+  @IsOptional()
+  id?: string
+
+  @IsString()
+  @IsOptional()
+  title?: string
+
+  @IsString()
+  @IsOptional()
+  sku?: string
+
+  @IsString()
+  @IsOptional()
+  ean?: string
+
+  @IsString()
+  @IsOptional()
+  upc?: string
+
+  @IsString()
+  @IsOptional()
+  barcode?: string
+
+  @IsString()
+  @IsOptional()
+  hs_code?: string
+
+  @IsInt()
+  @IsOptional()
+  inventory_quantity?: number
+
+  @IsBoolean()
+  @IsOptional()
+  allow_backorder?: boolean
+
+  @IsBoolean()
+  @IsOptional()
+  manage_inventory?: boolean
+
+  @IsNumber()
+  @IsOptional()
+  weight?: number
+
+  @IsNumber()
+  @IsOptional()
+  length?: number
+
+  @IsNumber()
+  @IsOptional()
+  height?: number
+
+  @IsNumber()
+  @IsOptional()
+  width?: number
+
+  @IsString()
+  @IsOptional()
+  origin_country?: string
+
+  @IsString()
+  @IsOptional()
+  mid_code?: string
+
+  @IsString()
+  @IsOptional()
+  material?: string
+
+  @IsObject()
+  @IsOptional()
+  metadata?: Record<string, unknown>
+
+  @IsArray()
+  @IsOptional()
+  @ValidateNested({ each: true })
+  @Type(() => ProductVariantPricesUpdateReq)
+  prices?: ProductVariantPricesUpdateReq[]
+
+  @IsOptional()
+  @Type(() => ProductVariantOptionReq)
+  @ValidateNested({ each: true })
+  @IsArray()
+  options?: ProductVariantOptionReq[] = []
+}
+
+/**
+ * @schema AdminPostProductsProductReq
  * type: object
  * properties:
  *   title:
@@ -229,176 +402,7 @@ import { validator } from "../../../../utils/validator"
  *   metadata:
  *     description: An optional set of key-value pairs with additional information.
  *     type: object
- * x-codeSamples:
- *   - lang: JavaScript
- *     label: JS Client
- *     source: |
- *       import Medusa from "@medusajs/medusa-js"
- *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
- *       // must be previously logged in or use api token
- *       medusa.admin.products.update(product_id, {
- *         title: 'Shirt',
- *         images: []
- *       })
- *       .then(({ product }) => {
- *         console.log(product.id);
- *       });
- *   - lang: Shell
- *     label: cURL
- *     source: |
- *       curl --location --request POST 'https://medusa-url.com/admin/products/{id}' \
- *       --header 'Authorization: Bearer {api_token}' \
- *       --header 'Content-Type: application/json' \
- *       --data-raw '{
- *           "title": "Size"
- *       }'
- * security:
- *   - api_token: []
- *   - cookie_auth: []
- * tags:
- *   - Product
- * responses:
- *   200:
- *     description: OK
- *     content:
- *       application/json:
- *         schema:
- *           type: object
- *           properties:
- *             product:
- *               $ref: "#/components/schemas/Product"
- *   "400":
- *     $ref: "#/components/responses/400_error"
- *   "401":
- *     $ref: "#/components/responses/unauthorized"
- *   "404":
- *     $ref: "#/components/responses/not_found_error"
- *   "409":
- *     $ref: "#/components/responses/invalid_state_error"
- *   "422":
- *     $ref: "#/components/responses/invalid_request_error"
- *   "500":
- *     $ref: "#/components/responses/500_error"
  */
-export default async (req, res) => {
-  const { id } = req.params
-
-  const validated = await validator(AdminPostProductsProductReq, req.body)
-
-  const productService: ProductService = req.scope.resolve("productService")
-  const pricingService: PricingService = req.scope.resolve("pricingService")
-
-  const manager: EntityManager = req.scope.resolve("manager")
-  await manager.transaction(async (transactionManager) => {
-    await productService
-      .withTransaction(transactionManager)
-      .update(id, validated)
-  })
-
-  const rawProduct = await productService.retrieve(id, {
-    select: defaultAdminProductFields,
-    relations: defaultAdminProductRelations,
-  })
-
-  const [product] = await pricingService.setProductPrices([rawProduct])
-
-  res.json({ product })
-}
-
-class ProductVariantOptionReq {
-  @IsString()
-  value: string
-
-  @IsString()
-  option_id: string
-}
-
-class ProductVariantReq {
-  @IsString()
-  @IsOptional()
-  id?: string
-
-  @IsString()
-  @IsOptional()
-  title?: string
-
-  @IsString()
-  @IsOptional()
-  sku?: string
-
-  @IsString()
-  @IsOptional()
-  ean?: string
-
-  @IsString()
-  @IsOptional()
-  upc?: string
-
-  @IsString()
-  @IsOptional()
-  barcode?: string
-
-  @IsString()
-  @IsOptional()
-  hs_code?: string
-
-  @IsInt()
-  @IsOptional()
-  inventory_quantity?: number
-
-  @IsBoolean()
-  @IsOptional()
-  allow_backorder?: boolean
-
-  @IsBoolean()
-  @IsOptional()
-  manage_inventory?: boolean
-
-  @IsNumber()
-  @IsOptional()
-  weight?: number
-
-  @IsNumber()
-  @IsOptional()
-  length?: number
-
-  @IsNumber()
-  @IsOptional()
-  height?: number
-
-  @IsNumber()
-  @IsOptional()
-  width?: number
-
-  @IsString()
-  @IsOptional()
-  origin_country?: string
-
-  @IsString()
-  @IsOptional()
-  mid_code?: string
-
-  @IsString()
-  @IsOptional()
-  material?: string
-
-  @IsObject()
-  @IsOptional()
-  metadata?: Record<string, unknown>
-
-  @IsArray()
-  @IsOptional()
-  @ValidateNested({ each: true })
-  @Type(() => ProductVariantPricesUpdateReq)
-  prices?: ProductVariantPricesUpdateReq[]
-
-  @IsOptional()
-  @Type(() => ProductVariantOptionReq)
-  @ValidateNested({ each: true })
-  @IsArray()
-  options?: ProductVariantOptionReq[] = []
-}
-
 export class AdminPostProductsProductReq {
   @IsString()
   @IsOptional()

packages/medusa/src/api/routes/admin/products/update-variant.ts

@@ -33,101 +33,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostProductsProductVariantsVariantReq"
- *         required:
- *           - prices
- *         properties:
- *           title:
- *             description: The title to identify the Product Variant by.
- *             type: string
- *           sku:
- *             description: The unique SKU for the Product Variant.
- *             type: string
- *           ean:
- *             description: The EAN number of the item.
- *             type: string
- *           upc:
- *             description: The UPC number of the item.
- *             type: string
- *           barcode:
- *             description: A generic GTIN field for the Product Variant.
- *             type: string
- *           hs_code:
- *             description: The Harmonized System code for the Product Variant.
- *             type: string
- *           inventory_quantity:
- *             description: The amount of stock kept for the Product Variant.
- *             type: integer
- *           allow_backorder:
- *             description: Whether the Product Variant can be purchased when out of stock.
- *             type: boolean
- *           manage_inventory:
- *             description: Whether Medusa should keep track of the inventory for this Product Variant.
- *             type: boolean
- *           weight:
- *             description: The weight of the Product Variant.
- *             type: number
- *           length:
- *             description: The length of the Product Variant.
- *             type: number
- *           height:
- *             description: The height of the Product Variant.
- *             type: number
- *           width:
- *             description: The width of the Product Variant.
- *             type: number
- *           origin_country:
- *             description: The country of origin of the Product Variant.
- *             type: string
- *           mid_code:
- *             description: The Manufacturer Identification code for the Product Variant.
- *             type: string
- *           material:
- *             description: The material composition of the Product Variant.
- *             type: string
- *           metadata:
- *             description: An optional set of key-value pairs with additional information.
- *             type: object
- *           prices:
- *             type: array
- *             items:
- *               required:
- *                 - amount
- *               properties:
- *                 id:
- *                   description: The ID of the price.
- *                   type: string
- *                 region_id:
- *                   description: The ID of the Region for which the price is used. Only required if currency_code is not provided.
- *                   type: string
- *                 currency_code:
- *                   description: The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided.
- *                   type: string
- *                   externalDocs:
- *                     url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
- *                     description: See a list of codes.
- *                 amount:
- *                   description: The amount to charge for the Product Variant.
- *                   type: integer
- *                 min_quantity:
- *                  description: The minimum quantity for which the price will be used.
- *                  type: integer
- *                 max_quantity:
- *                   description: The maximum quantity for which the price will be used.
- *                   type: integer
- *           options:
- *             type: array
- *             items:
- *               required:
- *                 - option_id
- *                 - value
- *               properties:
- *                 option_id:
- *                   description: The ID of the Product Option to set the value for.
- *                   type: string
- *                 value:
- *                   description: The value to give for the Product Option.
- *                   type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -242,6 +148,104 @@ class ProductVariantOptionReq {
   option_id: string
 }
 
+/**
+ * @schema AdminPostProductsProductVariantsVariantReq
+ * type: object
+ * required:
+ *   - prices
+ * properties:
+ *   title:
+ *     description: The title to identify the Product Variant by.
+ *     type: string
+ *   sku:
+ *     description: The unique SKU for the Product Variant.
+ *     type: string
+ *   ean:
+ *     description: The EAN number of the item.
+ *     type: string
+ *   upc:
+ *     description: The UPC number of the item.
+ *     type: string
+ *   barcode:
+ *     description: A generic GTIN field for the Product Variant.
+ *     type: string
+ *   hs_code:
+ *     description: The Harmonized System code for the Product Variant.
+ *     type: string
+ *   inventory_quantity:
+ *     description: The amount of stock kept for the Product Variant.
+ *     type: integer
+ *   allow_backorder:
+ *     description: Whether the Product Variant can be purchased when out of stock.
+ *     type: boolean
+ *   manage_inventory:
+ *     description: Whether Medusa should keep track of the inventory for this Product Variant.
+ *     type: boolean
+ *   weight:
+ *     description: The weight of the Product Variant.
+ *     type: number
+ *   length:
+ *     description: The length of the Product Variant.
+ *     type: number
+ *   height:
+ *     description: The height of the Product Variant.
+ *     type: number
+ *   width:
+ *     description: The width of the Product Variant.
+ *     type: number
+ *   origin_country:
+ *     description: The country of origin of the Product Variant.
+ *     type: string
+ *   mid_code:
+ *     description: The Manufacturer Identification code for the Product Variant.
+ *     type: string
+ *   material:
+ *     description: The material composition of the Product Variant.
+ *     type: string
+ *   metadata:
+ *     description: An optional set of key-value pairs with additional information.
+ *     type: object
+ *   prices:
+ *     type: array
+ *     items:
+ *       required:
+ *         - amount
+ *       properties:
+ *         id:
+ *           description: The ID of the price.
+ *           type: string
+ *         region_id:
+ *           description: The ID of the Region for which the price is used. Only required if currency_code is not provided.
+ *           type: string
+ *         currency_code:
+ *           description: The 3 character ISO currency code for which the price will be used. Only required if region_id is not provided.
+ *           type: string
+ *           externalDocs:
+ *             url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+ *             description: See a list of codes.
+ *         amount:
+ *           description: The amount to charge for the Product Variant.
+ *           type: integer
+ *         min_quantity:
+ *          description: The minimum quantity for which the price will be used.
+ *          type: integer
+ *         max_quantity:
+ *           description: The maximum quantity for which the price will be used.
+ *           type: integer
+ *   options:
+ *     type: array
+ *     items:
+ *       required:
+ *         - option_id
+ *         - value
+ *       properties:
+ *         option_id:
+ *           description: The ID of the Product Option to set the value for.
+ *           type: string
+ *         value:
+ *           description: The value to give for the Product Option.
+ *           type: string
+ */
 export class AdminPostProductsProductVariantsVariantReq {
   @IsString()
   @IsOptional()

packages/medusa/src/api/routes/admin/publishable-api-keys/add-channels-batch.ts

@@ -18,20 +18,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key"
  *   content:
  *     application/json:
  *       schema:
- *         required:
+ *         $ref: "#/components/schemas/AdminPostPublishableApiKeySalesChannelsBatchReq"
- *           - sales_channel_ids
- *         properties:
- *           sales_channel_ids:
- *             description: The IDs of the sales channels to add to the publishable api key
- *             type: array
- *             items:
- *               type: object
- *               required:
- *                 - id
- *               properties:
- *                 id:
- *                   type: string
- *                   description: The ID of the sales channel
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -116,6 +103,24 @@ export default async (req: Request, res: Response): Promise<void> => {
   res.status(200).json({ publishable_api_key: publishableApiKey })
 }
 
+/**
+ * @schema AdminPostPublishableApiKeySalesChannelsBatchReq
+ * type: object
+ * required:
+ *   - sales_channel_ids
+ * properties:
+ *   sales_channel_ids:
+ *     description: The IDs of the sales channels to add to the publishable api key
+ *     type: array
+ *     items:
+ *       type: object
+ *       required:
+ *         - id
+ *       properties:
+ *         id:
+ *           type: string
+ *           description: The ID of the sales channel
+ */
 export class AdminPostPublishableApiKeySalesChannelsBatchReq {
   @IsArray()
   @ValidateNested({ each: true })

packages/medusa/src/api/routes/admin/publishable-api-keys/create-publishable-api-key.ts

@@ -13,13 +13,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostPublishableApiKeysReq"
- *         required:
- *           - title
- *         properties:
- *           title:
- *             description: A title for the publishable api key
- *             type: string
  * x-authenticated: true
  * x-codeSamples:
  *   - lang: JavaScript
@@ -85,6 +79,16 @@ export default async (req: Request, res: Response) => {
   return res.status(200).json({ publishable_api_key: pubKey })
 }
 
+/**
+ * @schema AdminPostPublishableApiKeysReq
+ * type: object
+ * required:
+ *   - title
+ * properties:
+ *   title:
+ *     description: A title for the publishable api key
+ *     type: string
+ */
 export class AdminPostPublishableApiKeysReq {
   @IsString()
   title: string

packages/medusa/src/api/routes/admin/publishable-api-keys/delete-channels-batch.ts

@@ -18,20 +18,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key"
  *   content:
  *     application/json:
  *       schema:
- *         required:
+ *         $ref: "#/components/schemas/AdminDeletePublishableApiKeySalesChannelsBatchReq"
- *           - sales_channel_ids
- *         properties:
- *           sales_channel_ids:
- *             description: The IDs of the sales channels to delete from the publishable api key
- *             type: array
- *             items:
- *               type: object
- *               required:
- *                 - id
- *               properties:
- *                 id:
- *                   type: string
- *                   description: The ID of the sales channel
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -116,6 +103,24 @@ export default async (req: Request, res: Response): Promise<void> => {
   res.status(200).json({ publishable_api_key: publishableApiKey })
 }
 
+/**
+ * @schema AdminDeletePublishableApiKeySalesChannelsBatchReq
+ * type: object
+ * required:
+ *   - sales_channel_ids
+ * properties:
+ *   sales_channel_ids:
+ *     description: The IDs of the sales channels to delete from the publishable api key
+ *     type: array
+ *     items:
+ *       type: object
+ *       required:
+ *         - id
+ *       properties:
+ *         id:
+ *           type: string
+ *           description: The ID of the sales channel
+ */
 export class AdminDeletePublishableApiKeySalesChannelsBatchReq {
   @IsArray()
   @ValidateNested({ each: true })

packages/medusa/src/api/routes/admin/publishable-api-keys/update-publishable-api-key.ts

@@ -16,11 +16,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostPublishableApiKeysPublishableApiKeyReq"
- *         properties:
- *           title:
- *             description: A title to update for the key.
- *             type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -92,6 +88,14 @@ export default async (req: Request, res: Response) => {
   res.status(200).json({ publishable_api_key: updatedKey })
 }
 
+/**
+ * @schema AdminPostPublishableApiKeysPublishableApiKeyReq
+ * type: object
+ * properties:
+ *   title:
+ *     description: A title to update for the key.
+ *     type: string
+ */
 export class AdminPostPublishableApiKeysPublishableApiKeyReq {
   @IsString()
   @IsOptional()

packages/medusa/src/api/routes/admin/regions/add-country.ts

@@ -18,16 +18,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostRegionsRegionCountriesReq"
- *         required:
- *           - country_code
- *         properties:
- *           country_code:
- *             description: "The 2 character ISO code for the Country."
- *             type: string
- *             externalDocs:
- *               url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
- *               description: See a list of codes.
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -101,6 +92,19 @@ export default async (req, res) => {
   res.status(200).json({ region })
 }
 
+/**
+ * @schema AdminPostRegionsRegionCountriesReq
+ * type: object
+ * required:
+ *   - country_code
+ * properties:
+ *   country_code:
+ *     description: "The 2 character ISO code for the Country."
+ *     type: string
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
+ *       description: See a list of codes.
+ */
 export class AdminPostRegionsRegionCountriesReq {
   @IsString()
   country_code: string

packages/medusa/src/api/routes/admin/regions/add-fulfillment-provider.ts

@@ -18,13 +18,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostRegionsRegionFulfillmentProvidersReq"
- *         required:
- *           - provider_id
- *         properties:
- *           provider_id:
- *             description: "The ID of the Fulfillment Provider to add."
- *             type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -97,6 +91,16 @@ export default async (req, res) => {
   res.status(200).json({ region })
 }
 
+/**
+ * @schema AdminPostRegionsRegionFulfillmentProvidersReq
+ * type: object
+ * required:
+ *   - provider_id
+ * properties:
+ *   provider_id:
+ *     description: "The ID of the Fulfillment Provider to add."
+ *     type: string
+ */
 export class AdminPostRegionsRegionFulfillmentProvidersReq {
   @IsString()
   provider_id: string

packages/medusa/src/api/routes/admin/regions/add-payment-provider.ts

@@ -18,13 +18,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostRegionsRegionPaymentProvidersReq"
- *         required:
- *           - provider_id
- *         properties:
- *           provider_id:
- *             description: "The ID of the Payment Provider to add."
- *             type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -97,6 +91,16 @@ export default async (req, res) => {
   res.status(200).json({ region })
 }
 
+/**
+ * @schema AdminPostRegionsRegionPaymentProvidersReq
+ * type: object
+ * required:
+ *   - provider_id
+ * properties:
+ *   provider_id:
+ *     description: "The ID of the Payment Provider to add."
+ *     type: string
+ */
 export class AdminPostRegionsRegionPaymentProvidersReq {
   @IsString()
   provider_id: string

packages/medusa/src/api/routes/admin/regions/create-region.ts

@@ -24,49 +24,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostRegionsReq"
- *         required:
- *           - name
- *           - currency_code
- *           - tax_rate
- *           - payment_providers
- *           - fulfillment_providers
- *           - countries
- *         properties:
- *           name:
- *             description: "The name of the Region"
- *             type: string
- *           currency_code:
- *             description: "The 3 character ISO currency code to use for the Region."
- *             type: string
- *             externalDocs:
- *               url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
- *               description: See a list of codes.
- *           tax_code:
- *             description: "An optional tax code the Region."
- *             type: string
- *           tax_rate:
- *             description: "The tax rate to use on Orders in the Region."
- *             type: number
- *           payment_providers:
- *             description: "A list of Payment Provider IDs that should be enabled for the Region"
- *             type: array
- *             items:
- *               type: string
- *           fulfillment_providers:
- *             description: "A list of Fulfillment Provider IDs that should be enabled for the Region"
- *             type: array
- *             items:
- *               type: string
- *           countries:
- *             description: "A list of countries' 2 ISO Characters that should be included in the Region."
- *             example: ["US"]
- *             type: array
- *             items:
- *               type: string
- *           includes_tax:
- *             description: "[EXPERIMENTAL] Tax included in prices of region"
- *             type: boolean
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -160,6 +118,52 @@ export default async (req, res) => {
   res.status(200).json({ region })
 }
 
+/**
+ * @schema AdminPostRegionsReq
+ * type: object
+ * required:
+ *   - name
+ *   - currency_code
+ *   - tax_rate
+ *   - payment_providers
+ *   - fulfillment_providers
+ *   - countries
+ * properties:
+ *   name:
+ *     description: "The name of the Region"
+ *     type: string
+ *   currency_code:
+ *     description: "The 3 character ISO currency code to use for the Region."
+ *     type: string
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+ *       description: See a list of codes.
+ *   tax_code:
+ *     description: "An optional tax code the Region."
+ *     type: string
+ *   tax_rate:
+ *     description: "The tax rate to use on Orders in the Region."
+ *     type: number
+ *   payment_providers:
+ *     description: "A list of Payment Provider IDs that should be enabled for the Region"
+ *     type: array
+ *     items:
+ *       type: string
+ *   fulfillment_providers:
+ *     description: "A list of Fulfillment Provider IDs that should be enabled for the Region"
+ *     type: array
+ *     items:
+ *       type: string
+ *   countries:
+ *     description: "A list of countries' 2 ISO Characters that should be included in the Region."
+ *     example: ["US"]
+ *     type: array
+ *     items:
+ *       type: string
+ *   includes_tax:
+ *     description: "[EXPERIMENTAL] Tax included in prices of region"
+ *     type: boolean
+ */
 export class AdminPostRegionsReq {
   @IsString()
   name: string

packages/medusa/src/api/routes/admin/regions/update-region.ts

@@ -26,50 +26,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostRegionsRegionReq"
- *         properties:
- *           name:
- *             description: "The name of the Region"
- *             type: string
- *           currency_code:
- *             description: "The 3 character ISO currency code to use for the Region."
- *             type: string
- *             externalDocs:
- *               url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
- *               description: See a list of codes.
- *           automatic_taxes:
- *             description: "If true Medusa will automatically calculate taxes for carts in this region. If false you have to manually call POST /carts/:id/taxes."
- *             type: boolean
- *           gift_cards_taxable:
- *             description: "Whether gift cards in this region should be applied sales tax when purchasing a gift card"
- *             type: boolean
- *           tax_provider_id:
- *             description: "The ID of the tax provider to use; if null the system tax provider is used"
- *             type: string
- *           tax_code:
- *             description: "An optional tax code the Region."
- *             type: string
- *           tax_rate:
- *             description: "The tax rate to use on Orders in the Region."
- *             type: number
- *           includes_tax:
- *             description: "[EXPERIMENTAL] Tax included in prices of region"
- *             type: boolean
- *           payment_providers:
- *             description: "A list of Payment Provider IDs that should be enabled for the Region"
- *             type: array
- *             items:
- *               type: string
- *           fulfillment_providers:
- *             description: "A list of Fulfillment Provider IDs that should be enabled for the Region"
- *             type: array
- *             items:
- *               type: string
- *           countries:
- *             description: "A list of countries' 2 ISO Characters that should be included in the Region."
- *             type: array
- *             items:
- *               type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -140,6 +97,53 @@ export default async (req, res) => {
   res.status(200).json({ region })
 }
 
+/**
+ * @schema AdminPostRegionsRegionReq
+ * type: object
+ * properties:
+ *   name:
+ *     description: "The name of the Region"
+ *     type: string
+ *   currency_code:
+ *     description: "The 3 character ISO currency code to use for the Region."
+ *     type: string
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+ *       description: See a list of codes.
+ *   automatic_taxes:
+ *     description: "If true Medusa will automatically calculate taxes for carts in this region. If false you have to manually call POST /carts/:id/taxes."
+ *     type: boolean
+ *   gift_cards_taxable:
+ *     description: "Whether gift cards in this region should be applied sales tax when purchasing a gift card"
+ *     type: boolean
+ *   tax_provider_id:
+ *     description: "The ID of the tax provider to use; if null the system tax provider is used"
+ *     type: string
+ *   tax_code:
+ *     description: "An optional tax code the Region."
+ *     type: string
+ *   tax_rate:
+ *     description: "The tax rate to use on Orders in the Region."
+ *     type: number
+ *   includes_tax:
+ *     description: "[EXPERIMENTAL] Tax included in prices of region"
+ *     type: boolean
+ *   payment_providers:
+ *     description: "A list of Payment Provider IDs that should be enabled for the Region"
+ *     type: array
+ *     items:
+ *       type: string
+ *   fulfillment_providers:
+ *     description: "A list of Fulfillment Provider IDs that should be enabled for the Region"
+ *     type: array
+ *     items:
+ *       type: string
+ *   countries:
+ *     description: "A list of countries' 2 ISO Characters that should be included in the Region."
+ *     type: array
+ *     items:
+ *       type: string
+ */
 export class AdminPostRegionsRegionReq {
   @IsString()
   @IsOptional()

packages/medusa/src/api/routes/admin/return-reasons/create-reason.ts

@@ -18,26 +18,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostReturnReasonsReq"
- *         required:
- *          - label
- *          - value
- *         properties:
- *           label:
- *             description: "The label to display to the Customer."
- *             type: string
- *           value:
- *             description: "The value that the Return Reason will be identified by. Must be unique."
- *             type: string
- *           parent_return_reason_id:
- *             description: "The ID of the parent return reason."
- *             type: string
- *           description:
- *             description: "An optional description to for the Reason."
- *             type: string
- *           metadata:
- *             description: An optional set of key-value pairs with additional information.
- *             type: object
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -111,6 +92,29 @@ export default async (req, res) => {
   res.status(200).json({ return_reason: reason })
 }
 
+/**
+ * @schema AdminPostReturnReasonsReq
+ * type: object
+ * required:
+ *  - label
+ *  - value
+ * properties:
+ *   label:
+ *     description: "The label to display to the Customer."
+ *     type: string
+ *   value:
+ *     description: "The value that the Return Reason will be identified by. Must be unique."
+ *     type: string
+ *   parent_return_reason_id:
+ *     description: "The ID of the parent return reason."
+ *     type: string
+ *   description:
+ *     description: "An optional description to for the Reason."
+ *     type: string
+ *   metadata:
+ *     description: An optional set of key-value pairs with additional information.
+ *     type: object
+ */
 export class AdminPostReturnReasonsReq {
   @IsString()
   value: string

packages/medusa/src/api/routes/admin/return-reasons/update-reason.ts

@@ -20,20 +20,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostReturnReasonsReasonReq"
- *         properties:
- *           label:
- *             description: "The label to display to the Customer."
- *             type: string
- *           value:
- *             description: "The value that the Return Reason will be identified by. Must be unique."
- *             type: string
- *           description:
- *             description: "An optional description to for the Reason."
- *             type: string
- *           metadata:
- *             description: An optional set of key-value pairs with additional information.
- *             type: object
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -108,6 +95,23 @@ export default async (req, res) => {
   res.status(200).json({ return_reason: reason })
 }
 
+/**
+ * @schema AdminPostReturnReasonsReasonReq
+ * type: object
+ * properties:
+ *   label:
+ *     description: "The label to display to the Customer."
+ *     type: string
+ *   value:
+ *     description: "The value that the Return Reason will be identified by. Must be unique."
+ *     type: string
+ *   description:
+ *     description: "An optional description to for the Reason."
+ *     type: string
+ *   metadata:
+ *     description: An optional set of key-value pairs with additional information.
+ *     type: object
+ */
 export class AdminPostReturnReasonsReasonReq {
   @IsOptional()
   @IsString()

packages/medusa/src/api/routes/admin/returns/receive-return.ts

@@ -23,27 +23,7 @@ import { isDefined } from "medusa-core-utils"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostReturnsReturnReceiveReq"
- *         required:
- *           - items
- *         properties:
- *           items:
- *             description: The Line Items that have been received.
- *             type: array
- *             items:
- *               required:
- *                 - item_id
- *                 - quantity
- *               properties:
- *                 item_id:
- *                   description: The ID of the Line Item.
- *                   type: string
- *                 quantity:
- *                   description: The quantity of the Line Item.
- *                   type: integer
- *           refund:
- *             description: The amount to refund.
- *             type: number
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -156,6 +136,30 @@ class Item {
   quantity: number
 }
 
+/**
+ * @schema AdminPostReturnsReturnReceiveReq
+ * type: object
+ * required:
+ *   - items
+ * properties:
+ *   items:
+ *     description: The Line Items that have been received.
+ *     type: array
+ *     items:
+ *       required:
+ *         - item_id
+ *         - quantity
+ *       properties:
+ *         item_id:
+ *           description: The ID of the Line Item.
+ *           type: string
+ *         quantity:
+ *           description: The quantity of the Line Item.
+ *           type: integer
+ *   refund:
+ *     description: The amount to refund.
+ *     type: number
+ */
 export class AdminPostReturnsReturnReceiveReq {
   @IsArray()
   @ValidateNested({ each: true })

packages/medusa/src/api/routes/admin/sales-channels/add-product-batch.ts

@@ -18,21 +18,7 @@ import { Type } from "class-transformer"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostSalesChannelsChannelProductsBatchReq"
- *         required:
- *           - product_ids
- *         properties:
- *           product_ids:
- *             description: The IDs of the products to add to the Sales Channel
- *             type: array
- *             items:
- *               type: object
- *               required:
- *                 - id
- *               properties:
- *                 id:
- *                   type: string
- *                   description: The ID of the product
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -114,6 +100,24 @@ export default async (req: Request, res: Response): Promise<void> => {
   res.status(200).json({ sales_channel: salesChannel })
 }
 
+/**
+ * @schema AdminPostSalesChannelsChannelProductsBatchReq
+ * type: object
+ * required:
+ *   - product_ids
+ * properties:
+ *   product_ids:
+ *     description: The IDs of the products to add to the Sales Channel
+ *     type: array
+ *     items:
+ *       type: object
+ *       required:
+ *         - id
+ *       properties:
+ *         id:
+ *           type: string
+ *           description: The ID of the product
+ */
 export class AdminPostSalesChannelsChannelProductsBatchReq {
   @IsArray()
   @ValidateNested({ each: true })

packages/medusa/src/api/routes/admin/sales-channels/create-sales-channel.ts

@@ -15,19 +15,7 @@ import SalesChannelService from "../../../../services/sales-channel"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostSalesChannelsReq"
- *         required:
- *           - name
- *         properties:
- *           name:
- *             description: The name of the Sales Channel
- *             type: string
- *           description:
- *             description: The description of the Sales Channel
- *             type: string
- *           is_disabled:
- *             description: Whether the Sales Channel is disabled or not.
- *             type: boolean
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -96,6 +84,22 @@ export default async (req: Request, res: Response) => {
   res.status(200).json({ sales_channel: salesChannel })
 }
 
+/**
+ * @schema AdminPostSalesChannelsReq
+ * type: object
+ * required:
+ *   - name
+ * properties:
+ *   name:
+ *     description: The name of the Sales Channel
+ *     type: string
+ *   description:
+ *     description: The description of the Sales Channel
+ *     type: string
+ *   is_disabled:
+ *     description: Whether the Sales Channel is disabled or not.
+ *     type: boolean
+ */
 export class AdminPostSalesChannelsReq {
   @IsString()
   name: string

packages/medusa/src/api/routes/admin/sales-channels/delete-products-batch.ts

@@ -18,21 +18,7 @@ import { Type } from "class-transformer"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminDeleteSalesChannelsChannelProductsBatchReq"
- *         required:
- *           - product_ids
- *         properties:
- *           product_ids:
- *             description: The IDs of the products to delete from the Sales Channel.
- *             type: array
- *             items:
- *               type: object
- *               required:
- *                 - id
- *               properties:
- *                 id:
- *                   description: The ID of a product
- *                   type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -114,6 +100,24 @@ export default async (req: Request, res: Response) => {
   res.status(200).json({ sales_channel: salesChannel })
 }
 
+/**
+ * @schema AdminDeleteSalesChannelsChannelProductsBatchReq
+ * type: object
+ * required:
+ *   - product_ids
+ * properties:
+ *   product_ids:
+ *     description: The IDs of the products to delete from the Sales Channel.
+ *     type: array
+ *     items:
+ *       type: object
+ *       required:
+ *         - id
+ *       properties:
+ *         id:
+ *           description: The ID of a product
+ *           type: string
+ */
 export class AdminDeleteSalesChannelsChannelProductsBatchReq {
   @IsArray()
   @ValidateNested({ each: true })

packages/medusa/src/api/routes/admin/sales-channels/update-sales-channel.ts

@@ -16,17 +16,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostSalesChannelsSalesChannelReq"
- *         properties:
- *           name:
- *             type: string
- *             description: Name of the sales channel.
- *           description:
- *             type: string
- *             description:  Sales Channel description.
- *           is_disabled:
- *             type: boolean
- *             description:  Indication of if the sales channel is active.
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -98,6 +88,20 @@ export default async (req: Request, res: Response) => {
   res.status(200).json({ sales_channel })
 }
 
+/**
+ * @schema AdminPostSalesChannelsSalesChannelReq
+ * type: object
+ * properties:
+ *   name:
+ *     type: string
+ *     description: Name of the sales channel.
+ *   description:
+ *     type: string
+ *     description:  Sales Channel description.
+ *   is_disabled:
+ *     type: boolean
+ *     description:  Indication of if the sales channel is active.
+ */
 export class AdminPostSalesChannelsSalesChannelReq {
   @IsOptional()
   @IsString()

packages/medusa/src/api/routes/admin/shipping-options/create-shipping-option.ts

@@ -25,69 +25,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostShippingOptionsReq"
- *         required:
- *           - name
- *           - region_id
- *           - provider_id
- *           - data
- *           - price_type
- *         properties:
- *           name:
- *             description: "The name of the Shipping Option"
- *             type: string
- *           region_id:
- *             description: "The ID of the Region in which the Shipping Option will be available."
- *             type: string
- *           provider_id:
- *             description: "The ID of the Fulfillment Provider that handles the Shipping Option."
- *             type: string
- *           profile_id:
- *             description: "The ID of the Shipping Profile to add the Shipping Option to."
- *             type: number
- *           data:
- *             description: "The data needed for the Fulfillment Provider to handle shipping with this Shipping Option."
- *             type: object
- *           price_type:
- *             description: "The type of the Shipping Option price."
- *             type: string
- *             enum:
- *               - flat_rate
- *               - calculated
- *           amount:
- *             description: "The amount to charge for the Shipping Option."
- *             type: integer
- *           requirements:
- *             description: "The requirements that must be satisfied for the Shipping Option to be available."
- *             type: array
- *             items:
- *               required:
- *                 - type
- *                 - amount
- *               properties:
- *                 type:
- *                   description: The type of the requirement
- *                   type: string
- *                   enum:
- *                     - max_subtotal
- *                     - min_subtotal
- *                 amount:
- *                   description: The amount to compare with.
- *                   type: integer
- *           is_return:
- *             description: Whether the Shipping Option defines a return shipment.
- *             type: boolean
- *             default: false
- *           admin_only:
- *             description: If true, the option can be used for draft orders
- *             type: boolean
- *             default: false
- *           metadata:
- *             description: An optional set of key-value pairs with additional information.
- *             type: object
- *           includes_tax:
- *             description: "[EXPERIMENTAL] Tax included in prices of shipping option"
- *             type: boolean
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -181,6 +119,72 @@ class OptionRequirement {
   amount: number
 }
 
+/**
+ * @schema AdminPostShippingOptionsReq
+ * type: object
+ * required:
+ *   - name
+ *   - region_id
+ *   - provider_id
+ *   - data
+ *   - price_type
+ * properties:
+ *   name:
+ *     description: "The name of the Shipping Option"
+ *     type: string
+ *   region_id:
+ *     description: "The ID of the Region in which the Shipping Option will be available."
+ *     type: string
+ *   provider_id:
+ *     description: "The ID of the Fulfillment Provider that handles the Shipping Option."
+ *     type: string
+ *   profile_id:
+ *     description: "The ID of the Shipping Profile to add the Shipping Option to."
+ *     type: number
+ *   data:
+ *     description: "The data needed for the Fulfillment Provider to handle shipping with this Shipping Option."
+ *     type: object
+ *   price_type:
+ *     description: "The type of the Shipping Option price."
+ *     type: string
+ *     enum:
+ *       - flat_rate
+ *       - calculated
+ *   amount:
+ *     description: "The amount to charge for the Shipping Option."
+ *     type: integer
+ *   requirements:
+ *     description: "The requirements that must be satisfied for the Shipping Option to be available."
+ *     type: array
+ *     items:
+ *       required:
+ *         - type
+ *         - amount
+ *       properties:
+ *         type:
+ *           description: The type of the requirement
+ *           type: string
+ *           enum:
+ *             - max_subtotal
+ *             - min_subtotal
+ *         amount:
+ *           description: The amount to compare with.
+ *           type: integer
+ *   is_return:
+ *     description: Whether the Shipping Option defines a return shipment.
+ *     type: boolean
+ *     default: false
+ *   admin_only:
+ *     description: If true, the option can be used for draft orders
+ *     type: boolean
+ *     default: false
+ *   metadata:
+ *     description: An optional set of key-value pairs with additional information.
+ *     type: object
+ *   includes_tax:
+ *     description: "[EXPERIMENTAL] Tax included in prices of shipping option"
+ *     type: boolean
+ */
 export class AdminPostShippingOptionsReq {
   @IsString()
   name: string

packages/medusa/src/api/routes/admin/shipping-options/update-shipping-option.ts

@@ -27,45 +27,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostShippingOptionsOptionReq"
- *         required:
- *           - requirements
- *         properties:
- *           name:
- *             description: "The name of the Shipping Option"
- *             type: string
- *           amount:
- *             description: "The amount to charge for the Shipping Option."
- *             type: integer
- *           admin_only:
- *             description: "If true, the option can be used for draft orders"
- *             type: boolean
- *           metadata:
- *             description: "An optional set of key-value pairs with additional information."
- *             type: object
- *           requirements:
- *             description: "The requirements that must be satisfied for the Shipping Option to be available."
- *             type: array
- *             items:
- *               required:
- *                 - type
- *                 - amount
- *               properties:
- *                 id:
- *                   description: The ID of the requirement
- *                   type: string
- *                 type:
- *                   description: The type of the requirement
- *                   type: string
- *                   enum:
- *                     - max_subtotal
- *                     - min_subtotal
- *                 amount:
- *                   description: The amount to compare with.
- *                   type: integer
- *           includes_tax:
- *             description: "[EXPERIMENTAL] Tax included in prices of shipping option"
- *             type: boolean
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -160,6 +122,48 @@ class OptionRequirement {
   amount: number
 }
 
+/**
+ * @schema AdminPostShippingOptionsOptionReq
+ * type: object
+ * required:
+ *   - requirements
+ * properties:
+ *   name:
+ *     description: "The name of the Shipping Option"
+ *     type: string
+ *   amount:
+ *     description: "The amount to charge for the Shipping Option."
+ *     type: integer
+ *   admin_only:
+ *     description: "If true, the option can be used for draft orders"
+ *     type: boolean
+ *   metadata:
+ *     description: "An optional set of key-value pairs with additional information."
+ *     type: object
+ *   requirements:
+ *     description: "The requirements that must be satisfied for the Shipping Option to be available."
+ *     type: array
+ *     items:
+ *       required:
+ *         - type
+ *         - amount
+ *       properties:
+ *         id:
+ *           description: The ID of the requirement
+ *           type: string
+ *         type:
+ *           description: The type of the requirement
+ *           type: string
+ *           enum:
+ *             - max_subtotal
+ *             - min_subtotal
+ *         amount:
+ *           description: The amount to compare with.
+ *           type: integer
+ *   includes_tax:
+ *     description: "[EXPERIMENTAL] Tax included in prices of shipping option"
+ *     type: boolean
+ */
 export class AdminPostShippingOptionsOptionReq {
   @IsString()
   @IsOptional()

packages/medusa/src/api/routes/admin/shipping-profiles/create-shipping-profile.ts

@@ -13,13 +13,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostShippingProfilesReq"
- *         required:
- *           - name
- *         properties:
- *           name:
- *             description: "The name of the Shipping Profile"
- *             type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -86,6 +80,16 @@ export default async (req, res) => {
   res.status(200).json({ shipping_profile: data })
 }
 
+/**
+ * @schema AdminPostShippingProfilesReq
+ * type: object
+ * required:
+ *   - name
+ * properties:
+ *   name:
+ *     description: "The name of the Shipping Profile"
+ *     type: string
+ */
 export class AdminPostShippingProfilesReq {
   @IsString()
   name: string

packages/medusa/src/api/routes/admin/shipping-profiles/update-shipping-profile.ts

@@ -15,11 +15,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostShippingProfilesProfileReq"
- *         properties:
- *           name:
- *             description: "The name of the Shipping Profile"
- *             type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -93,6 +89,14 @@ export default async (req, res) => {
   res.status(200).json({ shipping_profile: data })
 }
 
+/**
+ * @schema AdminPostShippingProfilesProfileReq
+ * type: object
+ * properties:
+ *   name:
+ *     description: "The name of the Shipping Profile"
+ *     type: string
+ */
 export class AdminPostShippingProfilesProfileReq {
   @IsString()
   @IsOptional()

packages/medusa/src/api/routes/admin/store/update-store.ts

@@ -14,34 +14,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostStoreReq"
- *         properties:
- *           name:
- *             description: "The name of the Store"
- *             type: string
- *           swap_link_template:
- *             description: "A template for Swap links - use `{{cart_id}}` to insert the Swap Cart id"
- *             type: string
- *           payment_link_template:
- *             description: "A template for payment links links - use `{{cart_id}}` to insert the Cart id"
- *             type: string
- *           invite_link_template:
- *             description: "A template for invite links - use `{{invite_token}}` to insert the invite token"
- *             type: string
- *           default_currency_code:
- *             description: "The default currency code for the Store."
- *             type: string
- *             externalDocs:
- *               url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
- *               description: See a list of codes.
- *           currencies:
- *             description: "Array of currencies in 2 character ISO code format."
- *             type: array
- *             items:
- *               type: string
- *           metadata:
- *             description: "An optional set of key-value pairs with additional information."
- *             type: object
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -107,6 +80,37 @@ export default async (req, res) => {
   res.status(200).json({ store })
 }
 
+/**
+ * @schema AdminPostStoreReq
+ * type: object
+ * properties:
+ *   name:
+ *     description: "The name of the Store"
+ *     type: string
+ *   swap_link_template:
+ *     description: "A template for Swap links - use `{{cart_id}}` to insert the Swap Cart id"
+ *     type: string
+ *   payment_link_template:
+ *     description: "A template for payment links links - use `{{cart_id}}` to insert the Cart id"
+ *     type: string
+ *   invite_link_template:
+ *     description: "A template for invite links - use `{{invite_token}}` to insert the invite token"
+ *     type: string
+ *   default_currency_code:
+ *     description: "The default currency code for the Store."
+ *     type: string
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_4217#Active_codes
+ *       description: See a list of codes.
+ *   currencies:
+ *     description: "Array of currencies in 2 character ISO code format."
+ *     type: array
+ *     items:
+ *       type: string
+ *   metadata:
+ *     description: "An optional set of key-value pairs with additional information."
+ *     type: object
+ */
 export class AdminPostStoreReq {
   @IsOptional()
   @IsString()

packages/medusa/src/api/routes/admin/tax-rates/add-to-product-types.ts

@@ -36,15 +36,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostTaxRatesTaxRateProductTypesReq"
- *         required:
- *           - product_types
- *         properties:
- *           product_types:
- *             type: array
- *             description: "The IDs of the types of products to associate with this tax rate"
- *             items:
- *               type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -129,6 +121,18 @@ export default async (req, res) => {
   res.json({ tax_rate: data })
 }
 
+/**
+ * @schema AdminPostTaxRatesTaxRateProductTypesReq
+ * type: object
+ * required:
+ *   - product_types
+ * properties:
+ *   product_types:
+ *     type: array
+ *     description: "The IDs of the types of products to associate with this tax rate"
+ *     items:
+ *       type: string
+ */
 export class AdminPostTaxRatesTaxRateProductTypesReq {
   @IsArray()
   product_types: string[]

packages/medusa/src/api/routes/admin/tax-rates/add-to-products.ts

@@ -36,15 +36,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostTaxRatesTaxRateProductsReq"
- *         required:
- *           - products
- *         properties:
- *           products:
- *             type: array
- *             description: "The IDs of the products to associate with this tax rate"
- *             items:
- *               type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -126,6 +118,18 @@ export default async (req, res) => {
   res.json({ tax_rate: data })
 }
 
+/**
+ * @schema AdminPostTaxRatesTaxRateProductsReq
+ * type: object
+ * required:
+ *   - products
+ * properties:
+ *   products:
+ *     type: array
+ *     description: "The IDs of the products to associate with this tax rate"
+ *     items:
+ *       type: string
+ */
 export class AdminPostTaxRatesTaxRateProductsReq {
   @IsArray()
   products: string[]

packages/medusa/src/api/routes/admin/tax-rates/add-to-shipping-options.ts

@@ -36,15 +36,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostTaxRatesTaxRateShippingOptionsReq"
- *         required:
- *           - shipping_options
- *         properties:
- *           shipping_options:
- *             type: array
- *             description: "The IDs of the shipping options to associate with this tax rate"
- *             items:
- *               type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -128,6 +120,18 @@ export default async (req, res) => {
   res.json({ tax_rate: data })
 }
 
+/**
+ * @schema AdminPostTaxRatesTaxRateShippingOptionsReq
+ * type: object
+ * required:
+ *   - shipping_options
+ * properties:
+ *   shipping_options:
+ *     type: array
+ *     description: "The IDs of the shipping options to associate with this tax rate"
+ *     items:
+ *       type: string
+ */
 export class AdminPostTaxRatesTaxRateShippingOptionsReq {
   @IsArray()
   shipping_options: string[]

packages/medusa/src/api/routes/admin/tax-rates/create-tax-rate.ts

@@ -38,39 +38,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostTaxRatesReq"
- *         required:
- *           - code
- *           - name
- *           - region_id
- *         properties:
- *           code:
- *             type: string
- *             description: "A code to identify the tax type by"
- *           name:
- *             type: string
- *             description: "A human friendly name for the tax"
- *           region_id:
- *             type: string
- *             description: "The ID of the Region that the rate belongs to"
- *           rate:
- *             type: number
- *             description: "The numeric rate to charge"
- *           products:
- *             type: array
- *             description: "The IDs of the products associated with this tax rate"
- *             items:
- *               type: string
- *           shipping_options:
- *             type: array
- *             description: "The IDs of the shipping options associated with this tax rate"
- *             items:
- *               type: string
- *           product_types:
- *             type: array
- *             description: "The IDs of the types of products associated with this tax rate"
- *             items:
- *               type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -172,6 +140,42 @@ export default async (req, res) => {
   res.json({ tax_rate: data })
 }
 
+/**
+ * @schema AdminPostTaxRatesReq
+ * type: object
+ * required:
+ *   - code
+ *   - name
+ *   - region_id
+ * properties:
+ *   code:
+ *     type: string
+ *     description: "A code to identify the tax type by"
+ *   name:
+ *     type: string
+ *     description: "A human friendly name for the tax"
+ *   region_id:
+ *     type: string
+ *     description: "The ID of the Region that the rate belongs to"
+ *   rate:
+ *     type: number
+ *     description: "The numeric rate to charge"
+ *   products:
+ *     type: array
+ *     description: "The IDs of the products associated with this tax rate"
+ *     items:
+ *       type: string
+ *   shipping_options:
+ *     type: array
+ *     description: "The IDs of the shipping options associated with this tax rate"
+ *     items:
+ *       type: string
+ *   product_types:
+ *     type: array
+ *     description: "The IDs of the types of products associated with this tax rate"
+ *     items:
+ *       type: string
+ */
 export class AdminPostTaxRatesReq {
   @IsString()
   code: string

packages/medusa/src/api/routes/admin/tax-rates/remove-from-product-types.ts

@@ -36,15 +36,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminDeleteTaxRatesTaxRateProductTypesReq"
- *         required:
- *           - product_types
- *         properties:
- *           product_types:
- *             type: array
- *             description: "The IDs of the types of products to remove association with this tax rate"
- *             items:
- *               type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -129,6 +121,18 @@ export default async (req, res) => {
   res.json({ tax_rate: data })
 }
 
+/**
+ * @schema AdminDeleteTaxRatesTaxRateProductTypesReq
+ * type: object
+ * required:
+ *   - product_types
+ * properties:
+ *   product_types:
+ *     type: array
+ *     description: "The IDs of the types of products to remove association with this tax rate"
+ *     items:
+ *       type: string
+ */
 export class AdminDeleteTaxRatesTaxRateProductTypesReq {
   @IsArray()
   product_types: string[]

packages/medusa/src/api/routes/admin/tax-rates/remove-from-products.ts

@@ -36,15 +36,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminDeleteTaxRatesTaxRateProductsReq"
- *         required:
- *           - products
- *         properties:
- *           products:
- *             type: array
- *             description: "The IDs of the products to remove association with this tax rate"
- *             items:
- *               type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -126,6 +118,18 @@ export default async (req, res) => {
   res.json({ tax_rate: data })
 }
 
+/**
+ * @schema AdminDeleteTaxRatesTaxRateProductsReq
+ * type: object
+ * required:
+ *   - products
+ * properties:
+ *   products:
+ *     type: array
+ *     description: "The IDs of the products to remove association with this tax rate"
+ *     items:
+ *       type: string
+ */
 export class AdminDeleteTaxRatesTaxRateProductsReq {
   @IsArray()
   products: string[]

packages/medusa/src/api/routes/admin/tax-rates/remove-from-shipping-options.ts

@@ -36,15 +36,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminDeleteTaxRatesTaxRateShippingOptionsReq"
- *         required:
- *           - shipping_options
- *         properties:
- *           shipping_options:
- *             type: array
- *             description: "The IDs of the shipping options to remove association with this tax rate"
- *             items:
- *               type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -129,6 +121,18 @@ export default async (req, res) => {
   res.json({ tax_rate: data })
 }
 
+/**
+ * @schema AdminDeleteTaxRatesTaxRateShippingOptionsReq
+ * type: object
+ * required:
+ *   - shipping_options
+ * properties:
+ *   shipping_options:
+ *     type: array
+ *     description: "The IDs of the shipping options to remove association with this tax rate"
+ *     items:
+ *       type: string
+ */
 export class AdminDeleteTaxRatesTaxRateShippingOptionsReq {
   @IsArray()
   shipping_options: string[]

packages/medusa/src/api/routes/admin/tax-rates/update-tax-rate.ts

@@ -39,35 +39,7 @@ import { isDefined } from "medusa-core-utils"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostTaxRatesTaxRateReq"
- *         properties:
- *           code:
- *             type: string
- *             description: "A code to identify the tax type by"
- *           name:
- *             type: string
- *             description: "A human friendly name for the tax"
- *           region_id:
- *             type: string
- *             description: "The ID of the Region that the rate belongs to"
- *           rate:
- *             type: number
- *             description: "The numeric rate to charge"
- *           products:
- *             type: array
- *             description: "The IDs of the products associated with this tax rate"
- *             items:
- *               type: string
- *           shipping_options:
- *             type: array
- *             description: "The IDs of the shipping options associated with this tax rate"
- *             items:
- *               type: string
- *           product_types:
- *             type: array
- *             description: "The IDs of the types of products associated with this tax rate"
- *             items:
- *               type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -165,6 +137,38 @@ export default async (req, res) => {
   res.json({ tax_rate: data })
 }
 
+/**
+ * @schema AdminPostTaxRatesTaxRateReq
+ * type: object
+ * properties:
+ *   code:
+ *     type: string
+ *     description: "A code to identify the tax type by"
+ *   name:
+ *     type: string
+ *     description: "A human friendly name for the tax"
+ *   region_id:
+ *     type: string
+ *     description: "The ID of the Region that the rate belongs to"
+ *   rate:
+ *     type: number
+ *     description: "The numeric rate to charge"
+ *   products:
+ *     type: array
+ *     description: "The IDs of the products associated with this tax rate"
+ *     items:
+ *       type: string
+ *   shipping_options:
+ *     type: array
+ *     description: "The IDs of the shipping options associated with this tax rate"
+ *     items:
+ *       type: string
+ *   product_types:
+ *     type: array
+ *     description: "The IDs of the types of products associated with this tax rate"
+ *     items:
+ *       type: string
+ */
 export class AdminPostTaxRatesTaxRateReq {
   @IsOptional()
   @IsString()

packages/medusa/src/api/routes/admin/uploads/delete-upload.ts

@@ -10,13 +10,7 @@ import { IsString } from "class-validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminDeleteUploadsReq"
- *         required:
- *           - file_key
- *         properties:
- *           file_key:
- *             description: "key of the file to delete"
- *             type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -88,6 +82,16 @@ export default async (req, res) => {
     .send({ id: validated.file_key, object: "file", deleted: true })
 }
 
+/**
+ * @schema AdminDeleteUploadsReq
+ * type: object
+ * required:
+ *   - file_key
+ * properties:
+ *   file_key:
+ *     description: "key of the file to delete"
+ *     type: string
+ */
 export class AdminDeleteUploadsReq {
   @IsString()
   file_key: string

packages/medusa/src/api/routes/admin/uploads/get-download-url.ts

@@ -11,13 +11,7 @@ import { IsString } from "class-validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminPostUploadsDownloadUrlReq"
- *         required:
- *           - file_key
- *         properties:
- *           file_key:
- *             description: "key of the file to obtain the download link for"
- *             type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -79,6 +73,16 @@ export default async (req, res) => {
   res.status(200).send({ download_url: url })
 }
 
+/**
+ * @schema AdminPostUploadsDownloadUrlReq
+ * type: object
+ * required:
+ *   - file_key
+ * properties:
+ *   file_key:
+ *     description: "key of the file to obtain the download link for"
+ *     type: string
+ */
 export class AdminPostUploadsDownloadUrlReq {
   @IsString()
   file_key: string

packages/medusa/src/api/routes/admin/users/create-user.ts

@@ -16,29 +16,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminCreateUserRequest"
- *         required:
- *           - email
- *           - password
- *         properties:
- *           email:
- *             description: "The Users email."
- *             type: string
- *             format: email
- *           first_name:
- *             description: "The name of the User."
- *             type: string
- *           last_name:
- *             description: "The name of the User."
- *             type: string
- *           role:
- *             description: "Userrole assigned to the user."
- *             type: string
- *             enum: [admin, member, developer]
- *           password:
- *             description: "The Users password."
- *             type: string
- *             format: password
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -107,6 +85,32 @@ export default async (req, res) => {
   res.status(200).json({ user: _.omit(user, ["password_hash"]) })
 }
 
+/**
+ * @schema AdminCreateUserRequest
+ * type: object
+ * required:
+ *   - email
+ *   - password
+ * properties:
+ *   email:
+ *     description: "The Users email."
+ *     type: string
+ *     format: email
+ *   first_name:
+ *     description: "The name of the User."
+ *     type: string
+ *   last_name:
+ *     description: "The name of the User."
+ *     type: string
+ *   role:
+ *     description: "Userrole assigned to the user."
+ *     type: string
+ *     enum: [admin, member, developer]
+ *   password:
+ *     description: "The Users password."
+ *     type: string
+ *     format: password
+ */
 export class AdminCreateUserRequest {
   @IsEmail()
   email: string

packages/medusa/src/api/routes/admin/users/reset-password-token.ts

@@ -13,14 +13,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminResetPasswordTokenRequest"
- *         required:
- *           - email
- *         properties:
- *           email:
- *             description: "The Users email."
- *             type: string
- *             format: email
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -84,6 +77,17 @@ export default async (req, res) => {
   res.sendStatus(204)
 }
 
+/**
+ * @schema AdminResetPasswordTokenRequest
+ * type: object
+ * required:
+ *   - email
+ * properties:
+ *   email:
+ *     description: "The Users email."
+ *     type: string
+ *     format: email
+ */
 export class AdminResetPasswordTokenRequest {
   @IsEmail()
   email: string

packages/medusa/src/api/routes/admin/users/reset-password.ts

@@ -18,22 +18,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminResetPasswordRequest"
- *         required:
- *           - token
- *           - password
- *         properties:
- *           email:
- *             description: "The Users email."
- *             type: string
- *             format: email
- *           token:
- *             description: "The token generated from the 'password-token' endpoint."
- *             type: string
- *           password:
- *             description: "The Users new password."
- *             type: string
- *             format: password
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -137,6 +122,25 @@ export type payload = {
   password: string
 }
 
+/**
+ * @schema AdminResetPasswordRequest
+ * type: object
+ * required:
+ *   - token
+ *   - password
+ * properties:
+ *   email:
+ *     description: "The Users email."
+ *     type: string
+ *     format: email
+ *   token:
+ *     description: "The token generated from the 'password-token' endpoint."
+ *     type: string
+ *   password:
+ *     description: "The Users new password."
+ *     type: string
+ *     format: password
+ */
 export class AdminResetPasswordRequest {
   @IsEmail()
   @IsOptional()

packages/medusa/src/api/routes/admin/users/update-user.ts

@@ -17,24 +17,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/AdminUpdateUserRequest"
- *         properties:
- *           first_name:
- *             description: "The name of the User."
- *             type: string
- *           last_name:
- *             description: "The name of the User."
- *             type: string
- *           role:
- *             description: "Userrole assigned to the user."
- *             type: string
- *             enum: [admin, member, developer]
- *           api_token:
- *             description: "The api token of the User."
- *             type: string
- *           metadata:
- *             description: An optional set of key-value pairs with additional information.
- *             type: object
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -101,6 +84,27 @@ export default async (req, res) => {
   res.status(200).json({ user: data })
 }
 
+/**
+ * @schema AdminUpdateUserRequest
+ * type: object
+ * properties:
+ *   first_name:
+ *     description: "The name of the User."
+ *     type: string
+ *   last_name:
+ *     description: "The name of the User."
+ *     type: string
+ *   role:
+ *     description: "Userrole assigned to the user."
+ *     type: string
+ *     enum: [admin, member, developer]
+ *   api_token:
+ *     description: "The api token of the User."
+ *     type: string
+ *   metadata:
+ *     description: An optional set of key-value pairs with additional information.
+ *     type: object
+ */
 export class AdminUpdateUserRequest {
   @IsString()
   @IsOptional()

packages/medusa/src/api/routes/store/carts/create-cart.ts

@@ -36,40 +36,7 @@ import PublishableAPIKeysFeatureFlag from "../../../../loaders/feature-flags/pub
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/StorePostCartReq"
- *         properties:
- *           region_id:
- *             type: string
- *             description: The ID of the Region to create the Cart in.
- *           sales_channel_id:
- *             type: string
- *             description: "[EXPERIMENTAL] The ID of the Sales channel to create the Cart in."
- *           country_code:
- *             type: string
- *             description: "The 2 character ISO country code to create the Cart in."
- *             externalDocs:
- *              url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
- *              description: See a list of codes.
- *           items:
- *             description: "An optional array of `variant_id`, `quantity` pairs to generate Line Items from."
- *             type: array
- *             items:
- *               required:
- *                 - variant_id
- *                 - quantity
- *               properties:
- *                 variant_id:
- *                   description: The id of the Product Variant to generate a Line Item from.
- *                   type: string
- *                 quantity:
- *                   description: The quantity of the Product Variant to add
- *                   type: integer
- *           context:
- *             description: "An optional object to provide context to the Cart. The `context` field is automatically populated with `ip` and `user_agent`"
- *             type: object
- *             example:
- *               ip: "::1"
- *               user_agent: "Chrome"
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -223,6 +190,43 @@ export class Item {
   quantity: number
 }
 
+/**
+ * @schema StorePostCartReq
+ * type: object
+ * properties:
+ *   region_id:
+ *     type: string
+ *     description: The ID of the Region to create the Cart in.
+ *   sales_channel_id:
+ *     type: string
+ *     description: "[EXPERIMENTAL] The ID of the Sales channel to create the Cart in."
+ *   country_code:
+ *     type: string
+ *     description: "The 2 character ISO country code to create the Cart in."
+ *     externalDocs:
+ *      url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
+ *      description: See a list of codes.
+ *   items:
+ *     description: "An optional array of `variant_id`, `quantity` pairs to generate Line Items from."
+ *     type: array
+ *     items:
+ *       required:
+ *         - variant_id
+ *         - quantity
+ *       properties:
+ *         variant_id:
+ *           description: The id of the Product Variant to generate a Line Item from.
+ *           type: string
+ *         quantity:
+ *           description: The quantity of the Product Variant to add
+ *           type: integer
+ *   context:
+ *     description: "An optional object to provide context to the Cart. The `context` field is automatically populated with `ip` and `user_agent`"
+ *     type: object
+ *     example:
+ *       ip: "::1"
+ *       user_agent: "Chrome"
+ */
 export class StorePostCartReq {
   @IsOptional()
   @IsString()

packages/medusa/src/api/routes/store/carts/update-cart.ts

@@ -26,67 +26,7 @@ import { IsType } from "../../../../utils/validators/is-type"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/StorePostCartsCartReq"
- *         properties:
- *           region_id:
- *             type: string
- *             description: The id of the Region to create the Cart in.
- *           country_code:
- *             type: string
- *             description: "The 2 character ISO country code to create the Cart in."
- *             externalDocs:
- *               url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
- *               description: See a list of codes.
- *           email:
- *             type: string
- *             description: "An email to be used on the Cart."
- *             format: email
- *           sales_channel_id:
- *             type: string
- *             description: The ID of the Sales channel to update the Cart with.
- *           billing_address:
- *             description: "The Address to be used for billing purposes."
- *             anyOf:
- *               - $ref: "#/components/schemas/Address"
- *                 description: A full billing address object.
- *               - type: string
- *                 description: The billing address ID
- *           shipping_address:
- *             description: "The Address to be used for shipping."
- *             anyOf:
- *               - $ref: "#/components/schemas/Address"
- *                 description: A full shipping address object.
- *               - type: string
- *                 description: The shipping address ID
- *           gift_cards:
- *             description: "An array of Gift Card codes to add to the Cart."
- *             type: array
- *             items:
- *               required:
- *                 - code
- *               properties:
- *                 code:
- *                   description: "The code that a Gift Card is identified by."
- *                   type: string
- *           discounts:
- *             description: "An array of Discount codes to add to the Cart."
- *             type: array
- *             items:
- *               required:
- *                 - code
- *               properties:
- *                 code:
- *                   description: "The code that a Discount is identifed by."
- *                   type: string
- *           customer_id:
- *             description: "The ID of the Customer to associate the Cart with."
- *             type: string
- *           context:
- *             description: "An optional object to provide context to the Cart."
- *             type: object
- *             example:
- *               ip: "::1"
- *               user_agent: "Chrome"
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -174,6 +114,70 @@ class Discount {
   code: string
 }
 
+/**
+ * @schema StorePostCartsCartReq
+ * type: object
+ * properties:
+ *   region_id:
+ *     type: string
+ *     description: The id of the Region to create the Cart in.
+ *   country_code:
+ *     type: string
+ *     description: "The 2 character ISO country code to create the Cart in."
+ *     externalDocs:
+ *       url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
+ *       description: See a list of codes.
+ *   email:
+ *     type: string
+ *     description: "An email to be used on the Cart."
+ *     format: email
+ *   sales_channel_id:
+ *     type: string
+ *     description: The ID of the Sales channel to update the Cart with.
+ *   billing_address:
+ *     description: "The Address to be used for billing purposes."
+ *     anyOf:
+ *       - $ref: "#/components/schemas/Address"
+ *         description: A full billing address object.
+ *       - type: string
+ *         description: The billing address ID
+ *   shipping_address:
+ *     description: "The Address to be used for shipping."
+ *     anyOf:
+ *       - $ref: "#/components/schemas/Address"
+ *         description: A full shipping address object.
+ *       - type: string
+ *         description: The shipping address ID
+ *   gift_cards:
+ *     description: "An array of Gift Card codes to add to the Cart."
+ *     type: array
+ *     items:
+ *       required:
+ *         - code
+ *       properties:
+ *         code:
+ *           description: "The code that a Gift Card is identified by."
+ *           type: string
+ *   discounts:
+ *     description: "An array of Discount codes to add to the Cart."
+ *     type: array
+ *     items:
+ *       required:
+ *         - code
+ *       properties:
+ *         code:
+ *           description: "The code that a Discount is identifed by."
+ *           type: string
+ *   customer_id:
+ *     description: "The ID of the Customer to associate the Cart with."
+ *     type: string
+ *   context:
+ *     description: "An optional object to provide context to the Cart."
+ *     type: object
+ *     example:
+ *       ip: "::1"
+ *       user_agent: "Chrome"
+ */
 export class StorePostCartsCartReq {
   @IsOptional()
   @IsString()

packages/medusa/src/api/routes/store/customers/create-address.ts

@@ -16,22 +16,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/StorePostCustomersCustomerAddressesReq"
- *         required:
- *           - address
- *         properties:
- *           address:
- *             description: "The Address to add to the Customer."
- *             allOf:
- *               - $ref: "#/components/schemas/AddressFields"
- *               - type: object
- *                 required:
- *                   - first_name
- *                   - last_name
- *                   - address_1
- *                   - city
- *                   - country_code
- *                   - postal_code
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -125,6 +110,25 @@ export default async (req, res) => {
   res.status(200).json({ customer })
 }
 
+/**
+ * @schema StorePostCustomersCustomerAddressesReq
+ * type: object
+ * required:
+ *   - address
+ * properties:
+ *   address:
+ *     description: "The Address to add to the Customer."
+ *     allOf:
+ *       - $ref: "#/components/schemas/AddressFields"
+ *       - type: object
+ *         required:
+ *           - first_name
+ *           - last_name
+ *           - address_1
+ *           - city
+ *           - country_code
+ *           - postal_code
+ */
 export class StorePostCustomersCustomerAddressesReq {
   @ValidateNested()
   @Type(() => AddressCreatePayload)

packages/medusa/src/api/routes/store/customers/create-customer.ts

@@ -16,30 +16,7 @@ import { validator } from "../../../../utils/validator"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/StorePostCustomersReq"
- *         required:
- *           - first_name
- *           - last_name
- *           - email
- *           - password
- *         properties:
- *           first_name:
- *             description: "The Customer's first name."
- *             type: string
- *           last_name:
- *             description: "The Customer's last name."
- *             type: string
- *           email:
- *             description: "The email of the customer."
- *             type: string
- *             format: email
- *           password:
- *             description: "The Customer's password."
- *             type: string
- *             format: password
- *           phone:
- *             description: "The Customer's phone number."
- *             type: string
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -136,6 +113,33 @@ export default async (req, res) => {
   res.status(200).json({ customer })
 }
 
+/**
+ * @schema StorePostCustomersReq
+ * type: object
+ * required:
+ *   - first_name
+ *   - last_name
+ *   - email
+ *   - password
+ * properties:
+ *   first_name:
+ *     description: "The Customer's first name."
+ *     type: string
+ *   last_name:
+ *     description: "The Customer's last name."
+ *     type: string
+ *   email:
+ *     description: "The email of the customer."
+ *     type: string
+ *     format: email
+ *   password:
+ *     description: "The Customer's password."
+ *     type: string
+ *     format: password
+ *   phone:
+ *     description: "The Customer's phone number."
+ *     type: string
+ */
 export class StorePostCustomersReq {
   @IsString()
   @IsOptional()

packages/medusa/src/api/routes/store/customers/reset-password-token.ts

@@ -12,14 +12,7 @@ import { EntityManager } from "typeorm"
  *   content:
  *     application/json:
  *       schema:
- *         type: object
+ *         $ref: "#/components/schemas/StorePostCustomersCustomerPasswordTokenReq"
- *         required:
- *           - email
- *         properties:
- *           email:
- *             description: "The email of the customer."
- *             type: string
- *             format: email
  * x-codeSamples:
  *   - lang: JavaScript
  *     label: JS Client
@@ -86,6 +79,17 @@ export default async (req, res) => {
   res.sendStatus(204)
 }
 
+/**
+ * @schema StorePostCustomersCustomerPasswordTokenReq
+ * type: object
+ * required:
+ *   - email
+ * properties:
+ *   email:
+ *     description: "The email of the customer."
+ *     type: string
+ *     format: email
+ */
 export class StorePostCustomersCustomerPasswordTokenReq {
   @IsEmail()
   email: string