chore: improve JS Client TSDoc comments (#5582)

* add oas schema to tsdoc parser

* add tsdoc (part 1)

* Finished tsdoc in js client

* general fixes

* added tsdoc in core medusa package

* parse schema tags in model files

* added maxlevel option

* added more tsdoc

* added tsdoc in core

* added TSDoc in core package

* generated client types

* support featureFlag and expandable tags

* added support for resource feature flag note

* fix api ignore plugin

* added eslint plugin

* support feature flag and expandable badges

* adjusted overview page + generated reference

* revert generated files

* added changeset

* add details about new typedoc options

* fix broken link

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

@@ -33,7 +33,7 @@ import { validator } from "../../../../utils/validator"
  *       })
  *       .then(({ user }) => {
  *         console.log(user.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -19,7 +19,7 @@ import _ from "lodash"
  *       medusa.admin.auth.getSession()
  *       .then(({ user }) => {
  *         console.log(user.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

packages/medusa/src/api/routes/admin/auth/get-token.ts

@@ -30,7 +30,7 @@ import { AdminPostAuthReq } from "./create-session"
  *       })
  *       .then(({ access_token }) => {
  *         console.log(access_token);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

packages/medusa/src/api/routes/admin/auth/index.ts

@@ -29,6 +29,7 @@ export default (app) => {
 /**
  * @schema AdminAuthRes
  * type: object
+ * description: "The user's details."
  * required:
  *   - user
  * properties:
@@ -43,6 +44,7 @@ export type AdminAuthRes = {
 /**
  * @schema AdminBearerAuthRes
  * type: object
+ * description: "The access token of the user, if they're authenticated successfully."
  * properties:
  *   access_token:
  *     description: Access token that can be used to send authenticated requests.

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

@@ -21,7 +21,7 @@ import { EntityManager } from "typeorm"
  *       medusa.admin.batchJobs.cancel(batchJobId)
  *       .then(({ batch_job }) => {
  *         console.log(batch_job.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -21,7 +21,7 @@ import { EntityManager } from "typeorm"
  *       medusa.admin.batchJobs.confirm(batchJobId)
  *       .then(({ batch_job }) => {
  *         console.log(batch_job.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -35,7 +35,7 @@ import { validator } from "../../../../utils/validator"
  *         dry_run: false
  *       }).then((({ batch_job }) => {
  *         console.log(batch_job.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -102,7 +102,8 @@ export default async (req, res) => {
  * properties:
  *   type:
  *     type: string
- *     description: The type of batch job to start, which is defined by the `batchType` property of the associated batch job strategy.
+ *     description: >-
+ *       The type of batch job to start, which is defined by the `batchType` property of the associated batch job strategy.
  *     example: product-export
  *   context:
  *     type: object

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

@@ -18,7 +18,7 @@
  *       medusa.admin.batchJobs.retrieve(batchJobId)
  *       .then(({ batch_job }) => {
  *         console.log(batch_job.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

packages/medusa/src/api/routes/admin/batch/index.ts

@@ -45,6 +45,7 @@ export default (app) => {
 /**
  * @schema AdminBatchJobRes
  * type: object
+ * description: "The batch job's details."
  * required:
  *   - batch_job
  * properties:

packages/medusa/src/api/routes/admin/batch/list-batch-jobs.ts

@@ -276,40 +276,70 @@ export default async (req: Request, res) => {
   })
 }
 
+/**
+ * Request parameters used to configure and paginate retrieved batch jobs.
+ */
 export class AdminGetBatchPaginationParams {
+  /**
+   * {@inheritDoc FindPaginationParams.limit}
+   */
   @IsNumber()
   @IsOptional()
   @Type(() => Number)
   limit = 10
 
+  /**
+   * {@inheritDoc FindPaginationParams.offset}
+   */
   @IsNumber()
   @IsOptional()
   @Type(() => Number)
   offset = 0
 
+  /**
+   * {@inheritDoc FindParams.expand}
+   */
   @IsString()
   @IsOptional()
   expand?: string
 
+  /**
+   * {@inheritDoc FindParams.fields}
+   */
   @IsString()
   @IsOptional()
   fields?: string
 
+  /**
+   * The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
+   */
   @IsString()
   @IsOptional()
   order?: string
 }
 
+/**
+ * Parameters used to filter and configure pagination of the retrieved batch jobs.
+ */
 export class AdminGetBatchParams extends AdminGetBatchPaginationParams {
+  /**
+   * IDs to filter batch jobs by.
+   */
   @IsOptional()
   @IsArray()
   @IsType([String, [String]])
   id?: string | string[]
 
+  /**
+   * Types to filter batch jobs by.
+   */
   @IsArray()
   @IsOptional()
   type?: string[]
 
+  /**
+   * Date filters to apply on the batch jobs' `confirmed_at` date.
+   */
   @IsOptional()
   @Transform(({ value }) => {
     return value === "null" ? null : value
@@ -317,6 +347,9 @@ export class AdminGetBatchParams extends AdminGetBatchPaginationParams {
   @Type(() => DateComparisonOperator)
   confirmed_at?: DateComparisonOperator | null
 
+  /**
+   * Date filters to apply on the batch jobs' `pre_processed_at` date.
+   */
   @IsOptional()
   @Transform(({ value }) => {
     return value === "null" ? null : value
@@ -324,6 +357,9 @@ export class AdminGetBatchParams extends AdminGetBatchPaginationParams {
   @Type(() => DateComparisonOperator)
   pre_processed_at?: DateComparisonOperator | null
 
+  /**
+   * Date filters to apply on the batch jobs' `completed_at` date.
+   */
   @IsOptional()
   @Transform(({ value }) => {
     return value === "null" ? null : value
@@ -331,6 +367,9 @@ export class AdminGetBatchParams extends AdminGetBatchPaginationParams {
   @Type(() => DateComparisonOperator)
   completed_at?: DateComparisonOperator | null
 
+  /**
+   * Date filters to apply on the batch jobs' `failed_at` date.
+   */
   @IsOptional()
   @Transform(({ value }) => {
     return value === "null" ? null : value
@@ -338,6 +377,9 @@ export class AdminGetBatchParams extends AdminGetBatchPaginationParams {
   @Type(() => DateComparisonOperator)
   failed_at?: DateComparisonOperator | null
 
+  /**
+   * Date filters to apply on the batch jobs' `canceled_at` date.
+   */
   @IsOptional()
   @Transform(({ value }) => {
     return value === "null" ? null : value
@@ -345,10 +387,16 @@ export class AdminGetBatchParams extends AdminGetBatchPaginationParams {
   @Type(() => DateComparisonOperator)
   canceled_at?: DateComparisonOperator | null
 
+  /**
+   * Date filters to apply on the batch jobs' `created_at` date.
+   */
   @IsType([DateComparisonOperator])
   @IsOptional()
   created_at?: DateComparisonOperator
 
+  /**
+   * Date filters to apply on the batch jobs' `updated_at` date.
+   */
   @IsOptional()
   @Type(() => DateComparisonOperator)
   updated_at?: DateComparisonOperator

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

@@ -29,7 +29,7 @@ import { defaultAdminCollectionsRelations } from "."
  *       })
  *       .then(({ collection }) => {
  *         console.log(collection.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -23,7 +23,7 @@ import ProductCollectionService from "../../../../services/product-collection"
  *       medusa.admin.collections.delete(collectionId)
  *       .then(({ id, object, deleted }) => {
  *         console.log(id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -23,7 +23,7 @@ import { defaultAdminCollectionsRelations } from "."
  *       medusa.admin.collections.retrieve(collectionId)
  *       .then(({ collection }) => {
  *         console.log(collection.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

packages/medusa/src/api/routes/admin/collections/index.ts

@@ -122,6 +122,7 @@ export type AdminCollectionsDeleteRes = DeleteResponse
 /**
  * @schema AdminDeleteProductsFromCollectionRes
  * type: object
+ * description: "Deletion operation details"
  * required:
  *   - id
  *   - object
@@ -150,6 +151,7 @@ export type AdminDeleteProductsFromCollectionRes = {
 /**
  * @schema AdminCollectionsRes
  * type: object
+ * description: The collection's details.
  * x-expanded-relations:
  *   field: collection
  *   relations:
@@ -158,7 +160,7 @@ export type AdminDeleteProductsFromCollectionRes = {
  *   - collection
  * properties:
  *   collection:
- *     type: "Product Collection details."
+ *     description: "Product Collection details."
  *     $ref: "#/components/schemas/ProductCollection"
  */
 export type AdminCollectionsRes = {

packages/medusa/src/api/routes/admin/collections/list-collections.ts

@@ -97,7 +97,7 @@ import { Type } from "class-transformer"
  *       medusa.admin.collections.list()
  *       .then(({ collections, limit, offset, count }) => {
  *         console.log(collections.length);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -150,47 +150,80 @@ export default async (req: Request, res: Response) => {
   })
 }
 
+/**
+ * Parameters used to configure the pagination of the retrieved product collections.
+ */
 export class AdminGetCollectionsPaginationParams {
+  /**
+   * {@inheritDoc FindPaginationParams.limit}
+   */
   @IsNumber()
   @IsOptional()
   @Type(() => Number)
   limit = 10
 
+  /**
+   * {@inheritDoc FindPaginationParams.offset}
+   */
   @IsNumber()
   @IsOptional()
   @Type(() => Number)
   offset = 0
 }
 
+/**
+ * Parameters used to filter and configure the pagination of the retrieved product collections.
+ */
 // eslint-disable-next-line max-len
 export class AdminGetCollectionsParams extends AdminGetCollectionsPaginationParams {
+  /**
+   * Title to filter product collections by.
+   */
   @IsOptional()
   @IsString()
   title?: string
 
+  /**
+   * Handle to filter product collections by.
+   */
   @IsOptional()
   @IsString()
   handle?: string
 
+  /**
+   * Date filters to apply on the product collections' `created_at` date.
+   */
   @IsOptional()
   @ValidateNested()
   @Type(() => DateComparisonOperator)
   created_at?: DateComparisonOperator
 
+  /**
+   * Date filters to apply on the product collections' `updated_at` date.
+   */
   @IsOptional()
   @ValidateNested()
   @Type(() => DateComparisonOperator)
   updated_at?: DateComparisonOperator
 
+  /**
+   * Date filters to apply on the product collections' `deleted_at` date.
+   */
   @ValidateNested()
   @IsOptional()
   @Type(() => DateComparisonOperator)
   deleted_at?: DateComparisonOperator
 
+  /**
+   * Term to search product collections by their title and handle.
+   */
   @IsString()
   @IsOptional()
   q?: string
 
+  /**
+   * Filter product collections by their associated discount condition's ID.
+   */
   @IsString()
   @IsOptional()
   discount_condition_id?: string

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

@@ -31,7 +31,7 @@ import { defaultAdminCollectionsRelations } from "."
  *       })
  *       .then(({ collection }) => {
  *         console.log(collection.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

packages/medusa/src/api/routes/admin/currencies/index.ts

@@ -35,6 +35,7 @@ export default (app) => {
 /**
  * @schema AdminCurrenciesListRes
  * type: object
+ * description: List of currencies with pagination fields.
  * required:
  *   - currencies
  *   - count
@@ -63,6 +64,7 @@ export type AdminCurrenciesListRes = PaginatedResponse & {
 /**
  * @schema AdminCurrenciesRes
  * type: object
+ * description: A currency's details.
  * required:
  *   - currency
  * properties:

packages/medusa/src/api/routes/admin/currencies/list-currencies.ts

@@ -36,7 +36,7 @@ import { FeatureFlagDecorators } from "../../../../utils/feature-flag-decorators
  *       medusa.admin.currencies.list()
  *       .then(({ currencies, count, offset, limit }) => {
  *         console.log(currencies.length);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -78,17 +78,32 @@ export default async (req: ExtendedRequest<Currency>, res) => {
   })
 }
 
+/**
+ * Parameters used to filter and configure the pagination of the retrieved currencies.
+ */
 export class AdminGetCurrenciesParams extends FindPaginationParams {
+  /**
+   * Code to filter currencies by.
+   */
   @IsString()
   @IsOptional()
   code?: string
 
+  /**
+   * Filter currencies by whether they include tax.
+   *
+   * @featureFlag tax_inclusive_pricing
+   */
   @FeatureFlagDecorators(TaxInclusivePricingFeatureFlag.key, [
     IsBoolean(),
     IsOptional(),
   ])
   includes_tax?: boolean
 
+  /**
+   * The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
+   * By default, the returned currencies will be sorted by their `created_at` field.
+   */
   @IsString()
   @IsOptional()
   order?: string

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

@@ -33,7 +33,7 @@ import { EntityManager } from "typeorm"
  *       })
  *       .then(({ currency }) => {
  *         console.log(currency.code);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -38,7 +38,7 @@ import { validator } from "../../../../utils/validator"
  *       })
  *       .then(({ customer_group }) => {
  *         console.log(customer_group.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -9,7 +9,7 @@ import { validator } from "../../../../utils/validator"
  * @oas [post] /admin/customer-groups
  * operationId: "PostCustomerGroups"
  * summary: "Create a Customer Group"
- * description: "Creates a Customer Group."
+ * description: "Create a Customer Group."
  * x-authenticated: true
  * requestBody:
  *   content:
@@ -30,7 +30,7 @@ import { validator } from "../../../../utils/validator"
  *       })
  *       .then(({ customer_group }) => {
  *         console.log(customer_group.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -23,7 +23,7 @@ import { EntityManager } from "typeorm"
  *       medusa.admin.customerGroups.delete(customerGroupId)
  *       .then(({ id, object, deleted }) => {
  *         console.log(id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -38,7 +38,7 @@ import { validator } from "../../../../utils/validator"
  *       })
  *       .then(({ customer_group }) => {
  *         console.log(customer_group.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -29,7 +29,7 @@ import { Type } from "class-transformer"
  *       medusa.admin.customerGroups.listCustomers(customerGroupId)
  *       .then(({ customers }) => {
  *         console.log(customers.length);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -75,23 +75,38 @@ export default async (req: Request, res: Response) => {
   res.json(result)
 }
 
+/**
+ * Parameters used to filter and configure the pagination of the retrieved customer group's customers.
+ */
 // eslint-disable-next-line max-len
 export class AdminGetGroupsGroupCustomersParams {
+  /**
+   * Search term to search customers by their email, first name, and last name.
+   */
   @IsString()
   @IsOptional()
   q?: string
 
+  /**
+   * {@inheritDoc FindPaginationParams.limit}
+   */
   @IsNumber()
   @IsOptional()
   @Type(() => Number)
   limit = 50
 
+  /**
+   * {@inheritDoc FindPaginationParams.offset}
+   */
   @IsOptional()
   @IsNumber()
   @IsOptional()
   @Type(() => Number)
   offset = 0
 
+  /**
+   * {@inheritDoc FindParams.expand}
+   */
   @IsString()
   @IsOptional()
   expand?: string

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

@@ -26,7 +26,7 @@ import { FindParams } from "../../../../types/common"
  *       medusa.admin.customerGroups.retrieve(customerGroupId)
  *       .then(({ customer_group }) => {
  *         console.log(customer_group.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -59,6 +59,7 @@ export default (app) => {
 /**
  * @schema AdminCustomerGroupsRes
  * type: object
+ * description: "The customer group's details."
  * required:
  *   - customer_group
  * properties:

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

@@ -113,7 +113,7 @@ import { Type } from "class-transformer"
  *       medusa.admin.customerGroups.list()
  *       .then(({ customer_groups, limit, offset, count }) => {
  *         console.log(customer_groups.length);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -164,21 +164,36 @@ export default async (req: Request, res: Response) => {
   })
 }
 
+/**
+ * Parameters used to filter and configure the pagination of the retrieved customer groups.
+ */
 export class AdminGetCustomerGroupsParams extends FilterableCustomerGroupProps {
+  /**
+   * The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
+   */
   @IsString()
   @IsOptional()
   order?: string
 
+  /**
+   * {@inheritDoc FindPaginationParams.offset}
+   */
   @IsNumber()
   @IsOptional()
   @Type(() => Number)
   offset?: number = 0
 
+  /**
+   * {@inheritDoc FindPaginationParams.limit}
+   */
   @IsNumber()
   @IsOptional()
   @Type(() => Number)
   limit?: number = 10
 
+  /**
+   * {@inheritDoc FindParams.expand}
+   */
   @IsString()
   @IsOptional()
   expand?: string

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

@@ -34,7 +34,7 @@ import { validator } from "../../../../utils/validator"
  *       })
  *       .then(({ customer_group }) => {
  *         console.log(customer_group.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -8,7 +8,7 @@ import { EntityManager } from "typeorm"
  * @oas [post] /admin/customers
  * operationId: "PostCustomers"
  * summary: "Create a Customer"
- * description: "Allow admins to create a customer."
+ * description: "Create a customer as an admin."
  * x-authenticated: true
  * requestBody:
  *   content:
@@ -32,7 +32,7 @@ import { EntityManager } from "typeorm"
  *       })
  *       .then(({ customer }) => {
  *         console.log(customer.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -25,7 +25,7 @@ import { validator } from "../../../../utils/validator"
  *       medusa.admin.customers.retrieve(customerId)
  *       .then(({ customer }) => {
  *         console.log(customer.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

packages/medusa/src/api/routes/admin/customers/index.ts

@@ -23,6 +23,7 @@ export default (app) => {
 /**
  * @schema AdminCustomersRes
  * type: object
+ * description: "The customer's details."
  * x-expanded-relations:
  *   field: customer
  *   relations:
@@ -41,6 +42,7 @@ export type AdminCustomersRes = {
 
 /**
  * @schema AdminCustomersListRes
+ * description: The list of customers with pagination fields.
  * type: object
  * required:
  *   - customers

packages/medusa/src/api/routes/admin/customers/list-customers.ts

@@ -37,7 +37,7 @@ import customerController from "../../../../controllers/customers"
  *       medusa.admin.customers.list()
  *       .then(({ customers, limit, offset, count }) => {
  *         console.log(customers.length);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -79,18 +79,32 @@ export default async (req, res) => {
   res.json(result)
 }
 
+/**
+ * Parameters used to filter and configure the pagination of the retrieved customers.
+ */
 export class AdminGetCustomersParams extends AdminListCustomerSelector {
+  /**
+   * {@inheritDoc FindPaginationParams.limit}
+   * @defaultValue 50
+   */
   @IsNumber()
   @IsOptional()
   @Type(() => Number)
   limit = 50
 
+  /**
+   * {@inheritDoc FindPaginationParams.offset}
+   * @defaultValue 0
+   */
   @IsOptional()
   @IsNumber()
   @IsOptional()
   @Type(() => Number)
   offset = 0
 
+  /**
+   * {@inheritDoc FindParams.expand}
+   */
   @IsString()
   @IsOptional()
   expand?: string

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

@@ -44,7 +44,7 @@ import { validator } from "../../../../utils/validator"
  *       })
  *       .then(({ customer }) => {
  *         console.log(customer.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

packages/medusa/src/api/routes/admin/discounts/add-region.ts

@@ -25,7 +25,7 @@ import { EntityManager } from "typeorm"
  *       medusa.admin.discounts.addRegion(discountId, regionId)
  *       .then(({ discount }) => {
  *         console.log(discount.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -41,7 +41,7 @@ import { FindParams } from "../../../../types/common"
  *       })
  *       .then(({ discount }) => {
  *         console.log(discount.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -128,7 +128,7 @@ export default async (req: Request, res: Response) => {
  *         - id
  *       properties:
  *         id:
- *           description: The id of the item
+ *           description: The ID of the item
  *           type: string
  */
 export class AdminPostDiscountsDiscountConditionsConditionBatchReq {

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

@@ -36,11 +36,12 @@ import { FindParams } from "../../../../types/common"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
  *       medusa.admin.discounts.createCondition(discountId, {
- *         operator: DiscountConditionOperator.IN
+ *         operator: DiscountConditionOperator.IN,
+ *         products: [productId]
  *       })
  *       .then(({ discount }) => {
  *         console.log(discount.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -107,8 +108,9 @@ export default async (req: Request, res: Response) => {
  *   - operator
  * properties:
  *   operator:
- *      description: "Operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that
- *       discountable resources are everything but the specified resources."
+ *      description: >-
+ *        Operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that
+ *        discountable resources are everything but the specified resources.
  *      type: string
  *      enum: [in, not_in]
  *   products:

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

@@ -63,7 +63,7 @@ import { FindParams } from "../../../../types/common"
  *       })
  *       .then(({ discount }) => {
  *         console.log(discount.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -152,14 +152,16 @@ export default async (req: Request, res: Response) => {
  *         description: "A short description of the discount"
  *       type:
  *         type: string
- *         description: "The type of the discount, can be `fixed` for discounts that reduce the price by a fixed amount, `percentage` for percentage reductions or `free_shipping` for shipping vouchers."
+ *         description: >-
+ *           The type of the discount, can be `fixed` for discounts that reduce the price by a fixed amount, `percentage` for percentage reductions or `free_shipping` for shipping vouchers.
  *         enum: [fixed, percentage, free_shipping]
  *       value:
  *         type: number
  *         description: "The value that the discount represents. This will depend on the type of the discount."
  *       allocation:
  *         type: string
- *         description: "The scope that the discount should apply to. `total` indicates that the discount should be applied on the cart total, and `item` indicates that the discount should be applied to each discountable item in the cart."
+ *         description: >-
+ *           The scope that the discount should apply to. `total` indicates that the discount should be applied on the cart total, and `item` indicates that the discount should be applied to each discountable item in the cart.
  *         enum: [total, item]
  *       conditions:
  *         type: array
@@ -171,8 +173,9 @@ export default async (req: Request, res: Response) => {
  *           properties:
  *             operator:
  *               type: string
- *               description: "Operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that
- *                discountable resources are everything but the specified resources."
+ *               description: >-
+ *                 Operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that
+ *                 discountable resources are everything but the specified resources.
  *               enum: [in, not_in]
  *             products:
  *               type: array
@@ -201,7 +204,8 @@ export default async (req: Request, res: Response) => {
  *                 type: string
  *   is_disabled:
  *     type: boolean
- *     description: Whether the discount code is disabled on creation. If set to `true`, it will not be available for customers.
+ *     description: >-
+ *       Whether the discount code is disabled on creation. If set to `true`, it will not be available for customers.
  *     default: false
  *   starts_at:
  *     type: string
@@ -277,24 +281,42 @@ export class AdminPostDiscountsReq {
   metadata?: Record<string, unknown>
 }
 
+/**
+ * Details of the discount rule to create.
+ */
 export class AdminPostDiscountsDiscountRule {
+  /**
+   * The discount rule's description.
+   */
   @IsString()
   @IsOptional()
   description?: string
 
+  /**
+   * The discount rule's type.
+   */
   @IsEnum(DiscountRuleType, {
     message: `Invalid rule type, must be one of "fixed", "percentage" or "free_shipping"`,
   })
   type: DiscountRuleType
 
+  /**
+   * The discount rule's value.
+   */
   @IsNumber()
   value: number
 
+  /**
+   * The discount rule's allocation.
+   */
   @IsEnum(AllocationType, {
     message: `Invalid allocation type, must be one of "total" or "item"`,
   })
   allocation: AllocationType
 
+  /**
+   * The discount rule's conditions.
+   */
   @IsOptional()
   @IsArray()
   @ValidateNested({ each: true })
@@ -302,9 +324,18 @@ export class AdminPostDiscountsDiscountRule {
   conditions?: AdminCreateCondition[]
 }
 
+/**
+ * Details of the discount condition to create.
+ */
 export class AdminCreateCondition extends AdminUpsertConditionsReq {
+  /**
+   * The operator of the discount condition.
+   */
   @IsString()
   operator: DiscountConditionOperator
 }
 
+/**
+ * {@inheritDoc FindParams}
+ */
 export class AdminPostDiscountsParams extends FindParams {}

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

@@ -39,7 +39,7 @@ import { EntityManager } from "typeorm"
  *       })
  *       .then(({ discount }) => {
  *         console.log(discount.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -8,7 +8,7 @@ import { FindParams } from "../../../../types/common"
  * @oas [delete] /admin/discounts/{discount_id}/conditions/{condition_id}
  * operationId: "DeleteDiscountsDiscountConditionsCondition"
  * summary: "Delete a Condition"
- * description: "Deletes a Discount Condition. This does not delete resources associated to the discount condition."
+ * description: "Delete a Discount Condition. This does not delete resources associated to the discount condition."
  * x-authenticated: true
  * parameters:
  *   - (path) discount_id=* {string} The ID of the Discount
@@ -28,7 +28,7 @@ import { FindParams } from "../../../../types/common"
  *       medusa.admin.discounts.deleteCondition(discountId, conditionId)
  *       .then(({ id, object, deleted }) => {
  *         console.log(id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -21,7 +21,7 @@ import { EntityManager } from "typeorm"
  *       medusa.admin.discounts.delete(discountId)
  *       .then(({ id, object, deleted }) => {
  *         console.log(id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

packages/medusa/src/api/routes/admin/discounts/delete-dynamic-code.ts

@@ -24,7 +24,7 @@ import { EntityManager } from "typeorm"
  *       medusa.admin.discounts.deleteDynamicCode(discountId, code)
  *       .then(({ discount }) => {
  *         console.log(discount.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -12,7 +12,7 @@ import { FindParams } from "../../../../types/common"
  * @oas [delete] /admin/discounts/{discount_id}/conditions/{condition_id}/batch
  * operationId: "DeleteDiscountsDiscountConditionsConditionBatch"
  * summary: "Remove Batch Resources"
- * description: "Remove a batch of resources from a discount condition. This will only remove the association between the resource and the discount condition, but not the resource itself."
+ * description: "Remove a batch of resources from a discount condition. This will only remove the association between the resource and the discount condition, not the resource itself."
  * x-authenticated: true
  * parameters:
  *   - (path) discount_id=* {string} The ID of the discount.
@@ -38,7 +38,7 @@ import { FindParams } from "../../../../types/common"
  *       })
  *       .then(({ discount }) => {
  *         console.log(discount.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -110,12 +110,16 @@ export default async (req: Request, res: Response) => {
   res.status(200).json({ discount })
 }
 
+/**
+ * {@inheritDoc FindParams}
+ */
 // eslint-disable-next-line max-len
 export class AdminDeleteDiscountsDiscountConditionsConditionBatchParams extends FindParams {}
 
 /**
  * @schema AdminDeleteDiscountsDiscountConditionsConditionBatchReq
  * type: object
+ * description: "The resources to remove."
  * required:
  *   - resources
  * properties:

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

@@ -26,7 +26,7 @@ import { FindParams } from "../../../../types/common"
  *       medusa.admin.discounts.getCondition(discountId, conditionId)
  *       .then(({ discount_condition }) => {
  *         console.log(discount_condition.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

packages/medusa/src/api/routes/admin/discounts/get-discount-by-code.ts

@@ -25,7 +25,7 @@ import { FindParams } from "../../../../types/common"
  *       medusa.admin.discounts.retrieveByCode(code)
  *       .then(({ discount }) => {
  *         console.log(discount.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -6,7 +6,7 @@ import { FindParams } from "../../../../types/common"
  * @oas [get] /admin/discounts/{id}
  * operationId: "GetDiscountsDiscount"
  * summary: "Get a Discount"
- * description: "Retrieves a Discount"
+ * description: "Retrieve a Discount."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Discount
@@ -25,7 +25,7 @@ import { FindParams } from "../../../../types/common"
  *       medusa.admin.discounts.retrieve(discountId)
  *       .then(({ discount }) => {
  *         console.log(discount.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

packages/medusa/src/api/routes/admin/discounts/index.ts

@@ -222,6 +222,7 @@ export const defaultAdminDiscountConditionRelations = ["discount_rule"]
 /**
  * @schema AdminDiscountsRes
  * type: object
+ * description: "The discount's details."
  * x-expanded-relations:
  *   field: discount
  *   relations:
@@ -314,6 +315,7 @@ export type AdminDiscountConditionsDeleteRes = DeleteResponse & {
 /**
  * @schema AdminDiscountsListRes
  * type: object
+ * description: The list of discounts with pagination fields.
  * x-expanded-relations:
  *   field: discounts
  *   relations:
@@ -329,6 +331,7 @@ export type AdminDiscountConditionsDeleteRes = DeleteResponse & {
  * properties:
  *   discounts:
  *     type: array
+ *     description: "The list of discounts."
  *     items:
  *       $ref: "#/components/schemas/Discount"
  *   count:

packages/medusa/src/api/routes/admin/discounts/list-discounts.ts

@@ -52,7 +52,7 @@ import { optionalBooleanMapper } from "../../../../utils/validators/is-boolean"
  *       medusa.admin.discounts.list()
  *       .then(({ discounts, limit, offset, count }) => {
  *         console.log(discounts.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -103,24 +103,39 @@ export default async (req: Request, res: Response) => {
   })
 }
 
+/**
+ * Parameters used to filter and configure the pagination of the retrieved discounts.
+ */
 export class AdminGetDiscountsParams extends extendedFindParamsMixin({
   limit: 20,
   offset: 0,
 }) {
+  /**
+   * Filter discounts by their associated rule.
+   */
   @ValidateNested()
   @IsOptional()
   @Type(() => AdminGetDiscountsDiscountRuleParams)
   rule?: AdminGetDiscountsDiscountRuleParams
 
+  /**
+   * Search terms to search discounts' code fields.
+   */
   @IsString()
   @IsOptional()
   q?: string
 
+  /**
+   * Filter discounts by whether they're dynamic.
+   */
   @IsBoolean()
   @IsOptional()
   @Transform(({ value }) => optionalBooleanMapper.get(value))
   is_dynamic?: boolean
 
+  /**
+   * Filter discounts by whether they're disabled.
+   */
   @IsBoolean()
   @IsOptional()
   @Transform(({ value }) => optionalBooleanMapper.get(value))

packages/medusa/src/api/routes/admin/discounts/remove-region.ts

@@ -24,7 +24,7 @@ import { EntityManager } from "typeorm"
  *       medusa.admin.discounts.removeRegion(discountId, regionId)
  *       .then(({ discount }) => {
  *         console.log(discount.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -39,7 +39,7 @@ import { FindParams } from "../../../../types/common"
  *       })
  *       .then(({ discount }) => {
  *         console.log(discount.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -52,7 +52,7 @@ import { FindParams } from "../../../../types/common"
  *       })
  *       .then(({ discount }) => {
  *         console.log(discount.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -132,7 +132,8 @@ export default async (req: Request, res: Response) => {
  *         description: "The value that the discount represents. This will depend on the type of the discount."
  *       allocation:
  *         type: string
- *         description: "The scope that the discount should apply to. `total` indicates that the discount should be applied on the cart total, and `item` indicates that the discount should be applied to each discountable item in the cart."
+ *         description: >-
+ *           The scope that the discount should apply to. `total` indicates that the discount should be applied on the cart total, and `item` indicates that the discount should be applied to each discountable item in the cart.
  *         enum: [total, item]
  *       conditions:
  *         type: array
@@ -147,8 +148,9 @@ export default async (req: Request, res: Response) => {
  *               description: "The ID of the condition"
  *             operator:
  *               type: string
- *               description: "Operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that
- *                discountable resources are everything but the specified resources."
+ *               description: >-
+ *                 Operator of the condition. `in` indicates that discountable resources are within the specified resources. `not_in` indicates that
+ *                 discountable resources are everything but the specified resources.
  *               enum: [in, not_in]
  *             products:
  *               type: array
@@ -177,7 +179,8 @@ export default async (req: Request, res: Response) => {
  *                 type: string
  *   is_disabled:
  *     type: boolean
- *     description: Whether the discount code is disabled on creation. If set to `true`, it will not be available for customers.
+ *     description: >-
+ *       Whether the discount code is disabled on creation. If set to `true`, it will not be available for customers.
  *   starts_at:
  *     type: string
  *     format: date-time
@@ -249,25 +252,43 @@ export class AdminPostDiscountsDiscountReq {
   metadata?: Record<string, unknown>
 }
 
+/**
+ * The attributes of the discount rule to update.
+ */
 export class AdminUpdateDiscountRule {
+  /**
+   * The discount rule's ID.
+   */
   @IsString()
   @IsNotEmpty()
   id: string
 
+  /**
+   * The discount rule's description.
+   */
   @IsString()
   @IsOptional()
   description?: string
 
+  /**
+   * The discount rule's value.
+   */
   @IsNumber()
   @IsOptional()
   value?: number
 
+  /**
+   * The discount rule's allocation.
+   */
   @IsOptional()
   @IsEnum(AllocationType, {
     message: `Invalid allocation type, must be one of "total" or "item"`,
   })
   allocation?: AllocationType
 
+  /**
+   * The discount rule's discount conditions.
+   */
   @IsOptional()
   @IsArray()
   @ValidateNested({ each: true })
@@ -275,11 +296,20 @@ export class AdminUpdateDiscountRule {
   conditions?: AdminUpsertCondition[]
 }
 
+/**
+ * The attributes to create or update in the discount condition.
+ */
 export class AdminUpsertCondition extends AdminUpsertConditionsReq {
+  /**
+   * The discount condition's ID.
+   */
   @IsString()
   @IsOptional()
   id?: string
 
+  /**
+   * The discount condition's operator.
+   */
   @IsString()
   @IsOptional()
   operator: DiscountConditionOperator

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

@@ -63,7 +63,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  *       })
  *       .then(({ draft_order }) => {
  *         console.log(draft_order.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -173,7 +173,8 @@ enum Status {
  *   - shipping_methods
  * properties:
  *   status:
- *     description: "The status of the draft order. The draft order's default status is `open`. It's changed to `completed` when its payment is marked as paid."
+ *     description: >-
+ *       The status of the draft order. The draft order's default status is `open`. It's changed to `completed` when its payment is marked as paid.
  *     type: string
  *     enum: [open, completed]
  *   email:

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

@@ -48,7 +48,7 @@ import { validator } from "../../../../utils/validator"
  *       })
  *       .then(({ draft_order }) => {
  *         console.log(draft_order.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -5,7 +5,7 @@ import { EntityManager } from "typeorm"
  * @oas [delete] /admin/draft-orders/{id}
  * operationId: DeleteDraftOrdersDraftOrder
  * summary: Delete a Draft Order
- * description: "Delete a Draft Order"
+ * description: "Delete a Draft Order."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Draft Order.
@@ -21,7 +21,7 @@ import { EntityManager } from "typeorm"
  *       medusa.admin.draftOrders.delete(draftOrderId)
  *       .then(({ id, object, deleted }) => {
  *         console.log(id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -14,7 +14,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  * @oas [delete] /admin/draft-orders/{id}/line-items/{line_id}
  * operationId: DeleteDraftOrdersDraftOrderLineItemsItem
  * summary: Delete a Line Item
- * description: "Deletes a Line Item from a Draft Order."
+ * description: "Delete a Line Item from a Draft Order."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Draft Order.
@@ -31,7 +31,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  *       medusa.admin.draftOrders.removeLineItem(draftOrderId, itemId)
  *       .then(({ draft_order }) => {
  *         console.log(draft_order.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -29,7 +29,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  *       medusa.admin.draftOrders.retrieve(draftOrderId)
  *       .then(({ draft_order }) => {
  *         console.log(draft_order.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -94,6 +94,7 @@ export const defaultAdminDraftOrdersFields: (keyof DraftOrder)[] = [
 /**
  * @schema AdminPostDraftOrdersDraftOrderRegisterPaymentRes
  * type: object
+ * description: "The order's details."
  * required:
  *   - order
  * properties:
@@ -107,6 +108,7 @@ export type AdminPostDraftOrdersDraftOrderRegisterPaymentRes = {
 /**
  * @schema AdminDraftOrdersRes
  * type: object
+ * description: "The list of draft orders."
  * x-expanded-relations:
  *   field: draft_order
  *   relations:
@@ -201,6 +203,7 @@ export type AdminDraftOrdersDeleteRes = DeleteResponse
 
 /**
  * @schema AdminDraftOrdersListRes
+ * description: "The list of draft orders with pagination fields."
  * type: object
  * x-expanded-relations:
  *   field: draft_orders

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

@@ -34,7 +34,7 @@ import { validator } from "../../../../utils/validator"
  *       medusa.admin.draftOrders.list()
  *       .then(({ draft_orders, limit, offset, count }) => {
  *         console.log(draft_orders.length);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -100,16 +100,28 @@ export default async (req, res) => {
   })
 }
 
+/**
+ * Parameters used to filter and configure the pagination of the retrieved draft orders.
+ */
 export class AdminGetDraftOrdersParams {
+  /**
+   * Search term to search draft orders by their display IDs and emails.
+   */
   @IsString()
   @IsOptional()
   q?: string
 
+  /**
+   * {@inheritDoc FindPaginationParams.limit}
+   */
   @IsNumber()
   @IsOptional()
   @Type(() => Number)
   limit?: number = 50
 
+  /**
+   * {@inheritDoc FindPaginationParams.offset}
+   */
   @IsNumber()
   @IsOptional()
   @Type(() => Number)

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

@@ -37,7 +37,7 @@ import { promiseAll } from "@medusajs/utils"
  *       medusa.admin.draftOrders.markPaid(draftOrderId)
  *       .then(({ order }) => {
  *         console.log(order.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -48,7 +48,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  *       })
  *       .then(({ draft_order }) => {
  *         console.log(draft_order.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -17,7 +17,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  * @oas [post] /admin/draft-orders/{id}/line-items/{line_id}
  * operationId: "PostDraftOrdersDraftOrderLineItemsItem"
  * summary: "Update a Line Item"
- * description: "Update a Line Item in a Draft Order"
+ * description: "Update a Line Item in a Draft Order."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Draft Order.
@@ -41,7 +41,7 @@ import { cleanResponseData } from "../../../../utils/clean-response-data"
  *       })
  *       .then(({ draft_order }) => {
  *         console.log(draft_order.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -30,7 +30,7 @@ import { EntityManager } from "typeorm"
  *       })
  *       .then(({ gift_card }) => {
  *         console.log(gift_card.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -98,7 +98,8 @@ export default async (req, res) => {
  *     description: The value (excluding VAT) that the Gift Card should represent.
  *   is_disabled:
  *     type: boolean
- *     description: Whether the Gift Card is disabled on creation. If set to `true`, the gift card will not be available for customers.
+ *     description: >-
+ *       Whether the Gift Card is disabled on creation. If set to `true`, the gift card will not be available for customers.
  *   ends_at:
  *     type: string
  *     format: date-time

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

@@ -20,7 +20,7 @@ import { EntityManager } from "typeorm"
  *       medusa.admin.giftCards.delete(giftCardId)
  *       .then(({ id, object, deleted }) => {
  *         console.log(id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -20,7 +20,7 @@ import { defaultAdminGiftCardFields, defaultAdminGiftCardRelations } from "./"
  *       medusa.admin.giftCards.retrieve(giftCardId)
  *       .then(({ gift_card }) => {
  *         console.log(gift_card.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -59,6 +59,7 @@ export const defaultAdminGiftCardRelations = ["region", "order"]
 /**
  * @schema AdminGiftCardsRes
  * type: object
+ * description: "The gift card's details."
  * x-expanded-relations:
  *   field: gift_card
  *   relations:
@@ -103,6 +104,7 @@ export type AdminGiftCardsDeleteRes = DeleteResponse
 /**
  * @schema AdminGiftCardsListRes
  * type: object
+ * description: "The list of gift cards with pagination fields."
  * x-expanded-relations:
  *   field: gift_cards
  *   relations:
@@ -119,6 +121,7 @@ export type AdminGiftCardsDeleteRes = DeleteResponse
  * properties:
  *   gift_cards:
  *     type: array
+ *     description: "The list of gift cards."
  *     items:
  *       $ref: "#/components/schemas/GiftCard"
  *   count:

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

@@ -29,7 +29,7 @@ import { isDefined } from "medusa-core-utils"
  *       medusa.admin.giftCards.list()
  *       .then(({ gift_cards, limit, offset, count }) => {
  *         console.log(gift_cards.length);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -79,17 +79,31 @@ export default async (req, res) => {
   })
 }
 
+/**
+ * Parameters used to filter and configure the pagination of the retrieved gift cards.
+ */
 export class AdminGetGiftCardsParams {
+  /**
+   * {@inheritDoc FindPaginationParams.limit}
+   * @defaultValue 50
+   */
   @IsOptional()
   @IsInt()
   @Type(() => Number)
   limit = 50
 
+  /**
+   * {@inheritDoc FindPaginationParams.offset}
+   * @defaultValue 0
+   */
   @IsOptional()
   @IsInt()
   @Type(() => Number)
   offset = 0
 
+  /**
+   * Search term to search gift cards by their code and display ID.
+   */
   @IsOptional()
   @IsString()
   q?: string

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

@@ -33,7 +33,7 @@ import { validator } from "../../../../utils/validator"
  *       })
  *       .then(({ gift_card }) => {
  *         console.log(gift_card.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -100,7 +100,8 @@ export default async (req, res) => {
  *     description: The value (excluding VAT) that the Gift Card should represent.
  *   is_disabled:
  *     type: boolean
- *     description: Whether the Gift Card is disabled on creation. If set to `true`, the gift card will not be available for customers.
+ *     description: >-
+ *       Whether the Gift Card is disabled on creation. If set to `true`, the gift card will not be available for customers.
  *   ends_at:
  *     type: string
  *     format: date-time

packages/medusa/src/api/routes/admin/inventory-items/create-inventory-item.ts

@@ -39,7 +39,7 @@ import { MedusaError } from "@medusajs/utils"
  *       })
  *       .then(({ inventory_item }) => {
  *         console.log(inventory_item.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -158,7 +158,7 @@ function generateAttachInventoryToVariantHandler(
   productVariantInventoryService: ProductVariantInventoryService
 ) {
   return async ({ data }) => {
-    let inventoryItems = await productVariantInventoryService.listByVariant(
+    const inventoryItems = await productVariantInventoryService.listByVariant(
       variantId
     )
 
@@ -235,6 +235,15 @@ function generateAttachInventoryToVariantHandler(
  *   material:
  *     description: The material and composition that the Inventory Item is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.
  *     type: string
+ *   title:
+ *     description: The inventory item's title.
+ *     type: string
+ *   description:
+ *     description: The inventory item's description.
+ *     type: string
+ *   thumbnail:
+ *     description: The inventory item's thumbnail.
+ *     type: string
  *   metadata:
  *     description: An optional set of key-value pairs with additional information.
  *     type: object

packages/medusa/src/api/routes/admin/inventory-items/create-location-level.ts

@@ -6,8 +6,8 @@ import { FindParams } from "../../../../types/common"
 /**
  * @oas [post] /admin/inventory-items/{id}/location-levels
  * operationId: "PostInventoryItemsInventoryItemLocationLevels"
- * summary: "Create an Location Level"
- * description: "Create an Location Level for a given Inventory Item."
+ * summary: "Create a Location Level"
+ * description: "Create a Location Level for a given Inventory Item."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Inventory Item.
@@ -34,7 +34,7 @@ import { FindParams } from "../../../../types/common"
  *       })
  *       .then(({ inventory_item }) => {
  *         console.log(inventory_item.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

packages/medusa/src/api/routes/admin/inventory-items/delete-inventory-item.ts

@@ -21,9 +21,9 @@ import { ProductVariantInventoryService } from "../../../../services"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
  *       medusa.admin.inventoryItems.delete(inventoryItemId)
- *         .then(({ id, object, deleted }) => {
- *           console.log(id)
- *         })
+ *       .then(({ id, object, deleted }) => {
+ *         console.log(id)
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

packages/medusa/src/api/routes/admin/inventory-items/delete-location-level.ts

@@ -24,7 +24,7 @@ import { EntityManager } from "typeorm"
  *       medusa.admin.inventoryItems.deleteLocationLevel(inventoryItemId, locationId)
  *       .then(({ inventory_item }) => {
  *         console.log(inventory_item.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

packages/medusa/src/api/routes/admin/inventory-items/get-inventory-item.ts

@@ -26,7 +26,7 @@ import { joinLevels } from "./utils/join-levels"
  *       medusa.admin.inventoryItems.retrieve(inventoryItemId)
  *       .then(({ inventory_item }) => {
  *         console.log(inventory_item.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

packages/medusa/src/api/routes/admin/inventory-items/index.ts

@@ -166,6 +166,7 @@ export const defaultAdminInventoryItemRelations = []
 /**
  * @schema AdminInventoryItemsRes
  * type: object
+ * description: The inventory item's details.
  * required:
  *   - inventory_item
  * properties:
@@ -293,17 +294,20 @@ export type AdminInventoryItemsListWithVariantsAndLocationLevelsRes =
 /**
  * @schema AdminInventoryItemsLocationLevelsRes
  * type: object
+ * description: "Details of inventory items and their associated location levels."
  * required:
  *   - inventory_item
  * properties:
  *   inventory_item:
  *     type: object
+ *     description: "An inventory item's ID and associated location levels."
  *     required:
  *       - id
  *       - location_levels
  *     properties:
  *       id:
  *         description: The id of the location
+ *         type: string
  *       location_levels:
  *         description: List of stock levels at a given location
  *         type: array

packages/medusa/src/api/routes/admin/inventory-items/list-inventory-items.ts

@@ -76,7 +76,7 @@ import { Transform } from "class-transformer"
  *       medusa.admin.inventoryItems.list()
  *       .then(({ inventory_items, count, offset, limit }) => {
  *         console.log(inventory_items.length);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -150,58 +150,100 @@ export default async (req: Request, res: Response) => {
   })
 }
 
+/**
+ * Parameters used to filter and configure the pagination of the retrieved inventory items.
+ */
 export class AdminGetInventoryItemsParams extends extendedFindParamsMixin({
   limit: 20,
   offset: 0,
 }) {
+  /**
+   * IDs to filter inventory items by.
+   */
   @IsOptional()
   @IsType([String, [String]])
   id?: string | string[]
 
+  /**
+   * Search terms to search inventory items' sku, title, and description.
+   */
   @IsOptional()
   @IsString()
   q?: string
 
+  /**
+   * Location IDs to filter inventory items by.
+   */
   @IsOptional()
   @IsType([String, [String]])
   location_id?: string | string[]
 
+  /**
+   * SKUs to filter inventory items by.
+   */
   @IsOptional()
   @IsType([String, [String]])
   sku?: string | string[]
 
+  /**
+   * Origin countries to filter inventory items by.
+   */
   @IsOptional()
   @IsType([String, [String]])
   origin_country?: string | string[]
 
+  /**
+   * MID codes to filter inventory items by.
+   */
   @IsOptional()
   @IsType([String, [String]])
   mid_code?: string | string[]
 
+  /**
+   * Materials to filter inventory items by.
+   */
   @IsOptional()
   @IsType([String, [String]])
   material?: string | string[]
 
+  /**
+   * String filters to apply to inventory items' `hs_code` field.
+   */
   @IsOptional()
   @IsType([String, [String], StringComparisonOperator])
   hs_code?: string | string[] | StringComparisonOperator
 
+  /**
+   * Number filters to apply to inventory items' `weight` field.
+   */
   @IsOptional()
   @IsType([Number, NumericalComparisonOperator])
   weight?: number | NumericalComparisonOperator
 
+  /**
+   * Number filters to apply to inventory items' `length` field.
+   */
   @IsOptional()
   @IsType([Number, NumericalComparisonOperator])
   length?: number | NumericalComparisonOperator
 
+  /**
+   * Number filters to apply to inventory items' `height` field.
+   */
   @IsOptional()
   @IsType([Number, NumericalComparisonOperator])
   height?: number | NumericalComparisonOperator
 
+  /**
+   * Number filters to apply to inventory items' `width` field.
+   */
   @IsOptional()
   @IsType([Number, NumericalComparisonOperator])
   width?: number | NumericalComparisonOperator
 
+  /**
+   * Filter inventory items by whether they require shipping.
+   */
   @IsBoolean()
   @IsOptional()
   @Transform(({ value }) => value === "true")

packages/medusa/src/api/routes/admin/inventory-items/list-location-levels.ts

@@ -9,7 +9,7 @@ import { IsType } from "../../../../utils/validators/is-type"
  * @oas [get] /admin/inventory-items/{id}/location-levels
  * operationId: "GetInventoryItemsInventoryItemLocationLevels"
  * summary: "List Inventory Level"
- * description: "Retrieve a list of inventory levels of an inventory item. The inventory levels can be filtered by fields such as `location_id`. The inventory levels can also be paginated."
+ * description: "Retrieve a list of inventory levels of an inventory item. The inventory levels can be filtered by fields such as `location_id`."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the Inventory Item the locations are associated with.
@@ -37,7 +37,7 @@ import { IsType } from "../../../../utils/validators/is-type"
  *       medusa.admin.inventoryItems.listLocationLevels(inventoryItemId)
  *       .then(({ inventory_item }) => {
  *         console.log(inventory_item.location_levels);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -94,6 +94,9 @@ export default async (req: Request, res: Response) => {
 
 // eslint-disable-next-line max-len
 export class AdminGetInventoryItemsItemLocationLevelsParams extends FindParams {
+  /**
+   * Location IDs to filter location levels.
+   */
   @IsOptional()
   @IsString({ each: true })
   location_id?: string[]

packages/medusa/src/api/routes/admin/inventory-items/update-inventory-item.ts

@@ -35,7 +35,7 @@ import { IInventoryService } from "@medusajs/types"
  *       })
  *       .then(({ inventory_item }) => {
  *         console.log(inventory_item.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -94,6 +94,7 @@ export default async (req: Request, res: Response) => {
 /**
  * @schema AdminPostInventoryItemsInventoryItemReq
  * type: object
+ * description: "The attributes to update in an inventory item."
  * properties:
  *   hs_code:
  *     description: The Harmonized System code of the Inventory Item. May be used by Fulfillment Providers to pass customs information to shipping carriers.
@@ -119,6 +120,15 @@ export default async (req: Request, res: Response) => {
  *   length:
  *     description: The length of the Inventory Item. May be used in shipping rate calculations.
  *     type: number
+ *   title:
+ *     description: The inventory item's title.
+ *     type: string
+ *   description:
+ *     description: The inventory item's description.
+ *     type: string
+ *   thumbnail:
+ *     description: The inventory item's thumbnail.
+ *     type: string
  *   requires_shipping:
  *     description: Whether the item requires shipping.
  *     type: boolean

packages/medusa/src/api/routes/admin/inventory-items/update-location-level.ts

@@ -35,7 +35,7 @@ import { FindParams } from "../../../../types/common"
  *       })
  *       .then(({ inventory_item }) => {
  *         console.log(inventory_item.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -43,7 +43,7 @@ import { EntityManager } from "typeorm"
  *       })
  *       .catch(() => {
  *         // an error occurred
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -95,15 +95,27 @@ export default async (req, res) => {
   res.sendStatus(200)
 }
 
+/**
+ * Details of the use accepting the invite.
+ */
 export class AdminPostInvitesInviteAcceptUserReq {
+  /**
+   * The invite's first name.
+   */
   @IsString()
   @IsOptional()
   first_name: string
 
+  /**
+   * The invite's last name.
+   */
   @IsString()
   @IsOptional()
   last_name: string
 
+  /**
+   * The invite's password
+   */
   @IsString()
   password: string
 }
@@ -111,6 +123,7 @@ export class AdminPostInvitesInviteAcceptUserReq {
 /**
  * @schema AdminPostInvitesInviteAcceptReq
  * type: object
+ * description: "The details of the invite to be accepted."
  * required:
  *   - token
  *   - user

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

@@ -35,7 +35,7 @@ import { EntityManager } from "typeorm"
  *       })
  *       .catch(() => {
  *         // an error occurred
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -21,7 +21,7 @@ import InviteService from "../../../../services/invite"
  *       medusa.admin.invites.delete(inviteId)
  *       .then(({ id, object, deleted }) => {
  *         console.log(id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

packages/medusa/src/api/routes/admin/invites/index.ts

@@ -56,6 +56,7 @@ export type AdminInviteDeleteRes = DeleteResponse
 
 /**
  * @schema AdminListInvitesRes
+ * description: "The list of invites."
  * type: object
  * required:
  *   - invites

packages/medusa/src/api/routes/admin/invites/list-invites.ts

@@ -18,7 +18,7 @@ import InviteService from "../../../../services/invite"
  *       medusa.admin.invites.list()
  *       .then(({ invites }) => {
  *         console.log(invites.length);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -25,7 +25,7 @@ import { EntityManager } from "typeorm"
  *       })
  *       .catch(() => {
  *         // an error occurred
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -31,7 +31,7 @@ import { EntityManager } from "typeorm"
  *       })
  *       .then(({ note }) => {
  *         console.log(note.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -21,7 +21,7 @@ import NoteService from "../../../../services/note"
  *       medusa.admin.notes.delete(noteId)
  *       .then(({ id, object, deleted }) => {
  *         console.log(id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -20,7 +20,7 @@ import NoteService from "../../../../services/note"
  *       medusa.admin.notes.retrieve(noteId)
  *       .then(({ note }) => {
  *         console.log(note.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

packages/medusa/src/api/routes/admin/notes/index.ts

@@ -25,6 +25,7 @@ export default (app) => {
 /**
  * @schema AdminNotesRes
  * type: object
+ * description: "The note's details."
  * required:
  *   - note
  * properties:
@@ -61,6 +62,7 @@ export type AdminNotesDeleteRes = DeleteResponse
 /**
  * @schema AdminNotesListRes
  * type: object
+ * description: "The list of notes with pagination fields."
  * required:
  *   - notes
  *   - count

packages/medusa/src/api/routes/admin/notes/list-notes.ts

@@ -28,7 +28,7 @@ import { validator } from "../../../../utils/validator"
  *       medusa.admin.notes.list()
  *       .then(({ notes, limit, offset, count }) => {
  *         console.log(notes.length);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -84,16 +84,30 @@ export default async (req, res) => {
   })
 }
 
+/**
+ * Parameters used to filter and configure the pagination of the retrieved notes.
+ */
 export class AdminGetNotesParams {
+  /**
+   * Resource ID to filter notes by.
+   */
   @IsString()
   @IsOptional()
   resource_id?: string
 
+  /**
+   * {@inheritDoc FindPaginationParams.limit}
+   * @defaultValue 50
+   */
   @IsNumber()
   @IsOptional()
   @Type(() => Number)
   limit = 50
 
+  /**
+   * {@inheritDoc FindPaginationParams.offset}
+   * @defaultValue 0
+   */
   @IsNumber()
   @IsOptional()
   @Type(() => Number)

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

@@ -8,7 +8,7 @@ import { EntityManager } from "typeorm"
  * operationId: "PostNotesNote"
  * summary: "Update a Note"
  * x-authenticated: true
- * description: "Update a Note's details.'"
+ * description: "Update a Note's details."
  * parameters:
  *   - (path) id=* {string} The ID of the Note
  * requestBody:
@@ -30,7 +30,7 @@ import { EntityManager } from "typeorm"
  *       })
  *       .then(({ note }) => {
  *         console.log(note.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

packages/medusa/src/api/routes/admin/notifications/index.ts

@@ -69,6 +69,7 @@ export type AdminNotificationsListRes = PaginatedResponse & {
 /**
  * @schema AdminNotificationsRes
  * type: object
+ * description: "The notification's details."
  * x-expanded-relations:
  *   field: notification
  *   relations:

packages/medusa/src/api/routes/admin/notifications/list-notifications.ts

@@ -40,7 +40,7 @@ import { validator } from "../../../../utils/validator"
  *       medusa.admin.notifications.list()
  *       .then(({ notifications }) => {
  *         console.log(notifications.length);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -150,41 +150,73 @@ export default async (req, res) => {
   res.json({ notifications: data, count, limit, offset })
 }
 
+/**
+ * Parameters used to filter and configure the pagination of the retrieved notifications.
+ */
 export class AdminGetNotificationsParams {
+  /**
+   * {@inheritDoc FindPaginationParams.limit}
+   * @defaultValue 50
+   */
   @IsOptional()
   @IsInt()
   @Type(() => Number)
   limit?: number = 50
 
+  /**
+   * {@inheritDoc FindPaginationParams.offset}
+   * @defaultValue 0
+   */
   @IsOptional()
   @IsInt()
   @Type(() => Number)
   offset?: number = 0
 
+  /**
+   * {@inheritDoc FindParams.fields}
+   */
   @IsOptional()
   @IsString()
   fields?: string
 
+  /**
+   * {@inheritDoc FindParams.expand}
+   */
   @IsOptional()
   @IsString()
   expand?: string
 
+  /**
+   * Event name to filter notifications by.
+   */
   @IsOptional()
   @IsString()
   event_name?: string
 
+  /**
+   * Resource type to filter notifications by.
+   */
   @IsOptional()
   @IsString()
   resource_type?: string
 
+  /**
+   * Resource ID to filter notifications by.
+   */
   @IsOptional()
   @IsString()
   resource_id?: string
 
+  /**
+   * Filter notifications by their `to` field.
+   */
   @IsOptional()
   @IsString()
   to?: string
 
+  /**
+   * Whether to include resends in the results.
+   */
   @IsOptional()
   @IsBooleanString()
   include_resends?: string

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

@@ -34,7 +34,7 @@ import { validator } from "../../../../utils/validator"
  *       medusa.admin.notifications.resend(notificationId)
  *       .then(({ notification }) => {
  *         console.log(notification.id);
- *       });
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -104,7 +104,8 @@ export default async (req, res) => {
  * type: object
  * properties:
  *   to:
- *     description: "A new address or user identifier that the Notification should be sent to. If not provided, the previous `to` field of the notification will be used."
+ *     description: >-
+ *       A new address or user identifier that the Notification should be sent to. If not provided, the previous `to` field of the notification will be used.
  *     type: string
  */
 export class AdminPostNotificationsNotificationResendReq {

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

@@ -10,7 +10,7 @@ import {
  * @oas [post] /admin/order-edits/{id}/cancel
  * operationId: "PostOrderEditsOrderEditCancel"
  * summary: "Cancel an Order Edit"
- * description: "Cancel an OrderEdit."
+ * description: "Cancel an Order Edit."
  * x-authenticated: true
  * parameters:
  *   - (path) id=* {string} The ID of the OrderEdit.
@@ -24,9 +24,9 @@ import {
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
  *       medusa.admin.orderEdits.cancel(orderEditId)
- *         .then(({ order_edit }) => {
- *           console.log(order_edit.id)
- *         })
+ *       .then(({ order_edit }) => {
+ *         console.log(order_edit.id)
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -24,9 +24,9 @@ import {
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
  *       medusa.admin.orderEdits.confirm(orderEditId)
- *         .then(({ order_edit }) => {
- *           console.log(order_edit.id)
- *         })
+ *       .then(({ order_edit }) => {
+ *         console.log(order_edit.id)
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -28,9 +28,9 @@ import {
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
  *       medusa.admin.orderEdits.create({ orderId })
- *         .then(({ order_edit }) => {
- *           console.log(order_edit.id)
- *         })
+ *       .then(({ order_edit }) => {
+ *         console.log(order_edit.id)
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -26,9 +26,9 @@ import {
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
  *       medusa.admin.orderEdits.removeLineItem(orderEditId, lineItemId)
- *         .then(({ order_edit }) => {
- *           console.log(order_edit.id)
- *         })
+ *       .then(({ order_edit }) => {
+ *         console.log(order_edit.id)
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

packages/medusa/src/api/routes/admin/order-edits/delete-order-edit-item-change.ts

@@ -20,9 +20,9 @@ import { OrderEditService } from "../../../../services"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
  *       medusa.admin.orderEdits.deleteItemChange(orderEdit_id, itemChangeId)
- *         .then(({ id, object, deleted }) => {
- *           console.log(id)
- *         })
+ *       .then(({ id, object, deleted }) => {
+ *         console.log(id)
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -19,9 +19,9 @@ import { OrderEditService } from "../../../../services"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
  *       medusa.admin.orderEdits.delete(orderEditId)
- *         .then(({ id, object, deleted }) => {
- *           console.log(id)
- *         })
+ *       .then(({ id, object, deleted }) => {
+ *         console.log(id)
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -23,9 +23,9 @@ import { FindParams } from "../../../../types/common"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
  *       medusa.admin.orderEdits.retrieve(orderEditId)
- *         .then(({ order_edit }) => {
- *           console.log(order_edit.id)
- *         })
+ *       .then(({ order_edit }) => {
+ *         console.log(order_edit.id)
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |

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

@@ -101,6 +101,7 @@ export default (app) => {
 /**
  * @schema AdminOrderEditsRes
  * type: object
+ * description: "The order edit details."
  * x-expanded-relations:
  *   field: order_edit
  *   relations:
@@ -150,6 +151,7 @@ export type AdminOrderEditsRes = {
 /**
  * @schema AdminOrderEditsListRes
  * type: object
+ * description: "The list of order edits with pagination fields."
  * x-expanded-relations:
  *   field: order_edits
  *   relations:
@@ -235,6 +237,7 @@ export type AdminOrderEditDeleteRes = DeleteResponse
 /**
  * @schema AdminOrderEditItemChangeDeleteRes
  * type: object
+ * description: "The details of deleting order edit item changes."
  * required:
  *   - id
  *   - object

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

@@ -27,9 +27,9 @@ import { IsOptional, IsString } from "class-validator"
  *       const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
  *       // must be previously logged in or use api token
  *       medusa.admin.orderEdits.list()
- *         .then(({ order_edits, count, limit, offset }) => {
- *           console.log(order_edits.length)
- *         })
+ *       .then(({ order_edits, count, limit, offset }) => {
+ *         console.log(order_edits.length)
+ *       })
  *   - lang: Shell
  *     label: cURL
  *     source: |
@@ -85,14 +85,23 @@ export default async (req: Request, res: Response) => {
   })
 }
 
+/**
+ * Parameters used to filter and configure the pagination of the retrieved order edits.
+ */
 export class GetOrderEditsParams extends extendedFindParamsMixin({
   limit: 20,
   offset: 0,
 }) {
+  /**
+   * Search term to search order edits by their internal note.
+   */
   @IsString()
   @IsOptional()
   q?: string
 
+  /**
+   * Filter the order edits by their associated order's ID.
+   */
   @IsString()
   @IsOptional()
   order_id?: string