chore(oas): replace response with $ref to res class JSDoc OAS (A-C) (#3002)

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

@@ -37,10 +37,7 @@ import { validator } from "../../../../utils/validator"
  *    content:
  *      application/json:
  *        schema:
- *          type: object
+ *          $ref: "#/components/schemas/AdminAppsRes"
- *          properties:
- *            apps:
- *              $ref: "#/components/schemas/OAuth"
  *  "400":
  *    $ref: "#/components/responses/400_error"
  *  "401":

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

@@ -16,10 +16,26 @@ export default (app) => {
   return app
 }
 
+/**
+ * @schema AdminAppsRes
+ * type: object
+ * properties:
+ *   apps:
+ *     $ref: "#/components/schemas/OAuth"
+ */
 export type AdminAppsRes = {
   apps: Oauth
 }
 
+/**
+ * @schema AdminAppsListRes
+ * type: object
+ * properties:
+ *   apps:
+ *      type: array
+ *      items:
+ *        $ref: "#/components/schemas/OAuth"
+ */
 export type AdminAppsListRes = {
   apps: Oauth[]
 }

packages/medusa/src/api/routes/admin/apps/list.ts

@@ -23,12 +23,7 @@ import { OauthService } from "../../../../services"
  *    content:
  *      application/json:
  *        schema:
- *          type: object
+ *          $ref: "#/components/schemas/AdminAppsListRes"
- *          properties:
- *            apps:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/OAuth"
  *  "400":
  *    $ref: "#/components/responses/400_error"
  *  "401":

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

@@ -50,10 +50,7 @@ import { validator } from "../../../../utils/validator"
  *    content:
  *      application/json:
  *        schema:
- *          type: object
+ *          $ref: "#/components/schemas/AdminAuthRes"
- *          properties:
- *            user:
- *              $ref: "#/components/schemas/User"
  *  "400":
  *    $ref: "#/components/responses/400_error"
  *  "401":

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

@@ -34,10 +34,7 @@ import _ from "lodash"
  *    content:
  *      application/json:
  *        schema:
- *          type: object
+ *          $ref: "#/components/schemas/AdminAuthRes"
- *          properties:
- *            user:
- *              $ref: "#/components/schemas/User"
  *  "400":
  *    $ref: "#/components/responses/400_error"
  *  "401":

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

@@ -23,6 +23,13 @@ export default (app) => {
   return app
 }
 
+/**
+ * @schema AdminAuthRes
+ * type: object
+ * properties:
+ *   user:
+ *     $ref: "#/components/schemas/User"
+ */
 export type AdminAuthRes = {
   user: Omit<User, "password_hash">
 }

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

@@ -36,10 +36,7 @@ import { EntityManager } from "typeorm"
  *    content:
  *      application/json:
  *        schema:
- *          type: object
+ *          $ref: "#/components/schemas/AdminBatchJobRes"
- *          properties:
- *            batch_job:
- *              $ref: "#/components/schemas/BatchJob"
  *  "400":
  *    $ref: "#/components/responses/400_error"
  *  "401":

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

@@ -36,10 +36,7 @@ import { EntityManager } from "typeorm"
  *    content:
  *      application/json:
  *        schema:
- *          type: object
+ *          $ref: "#/components/schemas/AdminBatchJobRes"
- *          properties:
- *            batch_job:
- *              $ref: "#/components/schemas/BatchJob"
  *  "400":
  *    $ref: "#/components/responses/400_error"
  *  "401":

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

@@ -51,10 +51,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminBatchJobRes"
- *           properties:
- *            batch_job:
- *              $ref: "#/components/schemas/BatchJob"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -33,10 +33,7 @@
  *    content:
  *      application/json:
  *        schema:
- *          type: object
+ *          $ref: "#/components/schemas/AdminBatchJobRes"
- *          properties:
- *            batch_job:
- *              $ref: "#/components/schemas/BatchJob"
  *  "400":
  *    $ref: "#/components/responses/400_error"
  *  "401":

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

@@ -42,12 +42,35 @@ export default (app) => {
   return app
 }
 
+/**
+ * @schema AdminBatchJobRes
+ * type: object
+ * properties:
+ *   batch_job:
+ *     $ref: "#/components/schemas/BatchJob"
+ */
 export type AdminBatchJobRes = {
   batch_job: BatchJob
 }
 
-export type AdminBatchJobDeleteRes = DeleteResponse
+/**
-
+ * @schema AdminBatchJobListRes
+ * type: object
+ * properties:
+ *   batch_jobs:
+ *      type: array
+ *      items:
+ *        $ref: "#/components/schemas/BatchJob"
+ *   count:
+ *      type: integer
+ *      description: The total number of items available
+ *   offset:
+ *      type: integer
+ *      description: The number of items skipped before these items
+ *   limit:
+ *      type: integer
+ *      description: The number of items per page
+ */
 export type AdminBatchJobListRes = PaginatedResponse & {
   batch_jobs: BatchJob[]
 }

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

@@ -237,21 +237,7 @@ import { isDefined } from "medusa-core-utils"
  *    content:
  *      application/json:
  *        schema:
- *          type: object
+ *          $ref: "#/components/schemas/AdminBatchJobListRes"
- *          properties:
- *            batch_jobs:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/BatchJob"
- *            count:
- *               type: integer
- *               description: The total number of items available
- *            offset:
- *               type: integer
- *               description: The number of items skipped before these items
- *            limit:
- *               type: integer
- *               description: The number of items per page
  *  "400":
  *    $ref: "#/components/responses/400_error"
  *  "401":

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

@@ -40,10 +40,7 @@ import ProductCollectionService from "../../../../services/product-collection"
  *    content:
  *      application/json:
  *        schema:
- *          type: object
+ *          $ref: "#/components/schemas/AdminCollectionsRes"
- *          properties:
- *            collection:
- *              $ref: "#/components/schemas/ProductCollection"
  *  "400":
  *    $ref: "#/components/responses/400_error"
  *  "401":

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

@@ -47,10 +47,7 @@ import { EntityManager } from "typeorm"
  *    content:
  *      application/json:
  *        schema:
- *          type: object
+ *          $ref: "#/components/schemas/AdminCollectionsRes"
- *          properties:
- *            collection:
- *              $ref: "#/components/schemas/ProductCollection"
  *  "400":
  *    $ref: "#/components/responses/400_error"
  *  "401":

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

@@ -38,19 +38,7 @@ import ProductCollectionService from "../../../../services/product-collection"
  *    content:
  *      application/json:
  *        schema:
- *          type: object
+ *          $ref: "#/components/schemas/AdminCollectionsDeleteRes"
- *          properties:
- *            id:
- *              type: string
- *              description: The ID of the deleted Collection
- *            object:
- *              type: string
- *              description: The type of the object that was deleted.
- *              default: product-collection
- *            deleted:
- *              type: boolean
- *              description: Whether the collection was deleted successfully or not.
- *              default: true
  *  "400":
  *    $ref: "#/components/responses/400_error"
  *  "401":

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

@@ -38,10 +38,7 @@ import { defaultAdminCollectionsRelations } from "."
  *    content:
  *      application/json:
  *        schema:
- *          type: object
+ *          $ref: "#/components/schemas/AdminCollectionsRes"
- *          properties:
- *            collection:
- *              $ref: "#/components/schemas/ProductCollection"
  *  "400":
  *    $ref: "#/components/responses/400_error"
  *  "401":

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

@@ -69,12 +69,77 @@ export const defaultAdminCollectionsFields = [
 ]
 export const defaultAdminCollectionsRelations = ["products"]
 
+/**
+ * @schema AdminCollectionsListRes
+ * type: object
+ * properties:
+ *   collections:
+ *      type: array
+ *      items:
+ *        $ref: "#/components/schemas/ProductCollection"
+ *   count:
+ *      type: integer
+ *      description: The total number of items available
+ *   offset:
+ *      type: integer
+ *      description: The number of items skipped before these items
+ *   limit:
+ *      type: integer
+ *      description: The number of items per page
+ */
 export type AdminCollectionsListRes = PaginatedResponse & {
   collections: ProductCollection[]
 }
 
+/**
+ * @schema AdminCollectionsDeleteRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted Collection
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: product-collection
+ *   deleted:
+ *     type: boolean
+ *     description: Whether the collection was deleted successfully or not.
+ *     default: true
+ */
 export type AdminCollectionsDeleteRes = DeleteResponse
 
+/**
+ * @schema AdminDeleteProductsFromCollectionRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: "The ID of the collection"
+ *   object:
+ *     type: string
+ *     description: "The type of object the removal was executed on"
+ *     default: product-collection
+ *   removed_products:
+ *     description: "The IDs of the products removed from the collection"
+ *     type: array
+ *     items:
+ *       description: "The ID of a Product to add to the Product Collection."
+ *       type: string
+ */
+export type AdminDeleteProductsFromCollectionRes = {
+  id: string
+  object: string
+  removed_products: string[]
+}
+
+/**
+ * @schema AdminCollectionsRes
+ * type: object
+ * properties:
+ *   collection:
+ *     $ref: "#/components/schemas/ProductCollection"
+ */
 export type AdminCollectionsRes = {
   collection: ProductCollection
 }

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

@@ -111,21 +111,7 @@ import { Type } from "class-transformer"
  *    content:
  *      application/json:
  *        schema:
- *          type: object
+ *          $ref: "#/components/schemas/AdminCollectionsListRes"
- *          properties:
- *            collections:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/ProductCollection"
- *            count:
- *               type: integer
- *               description: The total number of items available
- *            offset:
- *               type: integer
- *               description: The number of items skipped before these items
- *            limit:
- *               type: integer
- *               description: The number of items per page
  *  "400":
  *    $ref: "#/components/responses/400_error"
  *  "401":

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

@@ -40,21 +40,7 @@ import ProductCollectionService from "../../../../services/product-collection"
  *    content:
  *      application/json:
  *        schema:
- *          type: object
+ *          $ref: "#/components/schemas/AdminDeleteProductsFromCollectionRes"
- *          properties:
- *            id:
- *              type: string
- *              description: "The ID of the collection"
- *            object:
- *              type: string
- *              description: "The type of object the removal was executed on"
- *              default: product-collection
- *            removed_products:
- *              description: "The IDs of the products removed from the collection"
- *              type: array
- *              items:
- *                description: "The ID of a Product to add to the Product Collection."
- *                type: string
  *  "400":
  *    $ref: "#/components/responses/400_error"
  *  "401":

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

@@ -49,10 +49,7 @@ import ProductCollectionService from "../../../../services/product-collection"
  *    content:
  *      application/json:
  *        schema:
- *          type: object
+ *          $ref: "#/components/schemas/AdminCollectionsRes"
- *          properties:
- *            collection:
- *              $ref: "#/components/schemas/ProductCollection"
  *  "400":
  *    $ref: "#/components/responses/400_error"
  *  "401":

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

@@ -32,10 +32,35 @@ export default (app) => {
   return app
 }
 
+/**
+ * @schema AdminCurrenciesListRes
+ * type: object
+ * properties:
+ *   currencies:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/Currency"
+ *   count:
+ *     type: integer
+ *     description: The total number of items available
+ *   offset:
+ *     type: integer
+ *     description: The number of items skipped before these items
+ *   limit:
+ *     type: integer
+ *     description: The number of items per page
+ */
 export type AdminCurrenciesListRes = PaginatedResponse & {
   currencies: Currency[]
 }
 
+/**
+ * @schema AdminCurrenciesRes
+ * type: object
+ * properties:
+ *   currency:
+ *       $ref: "#/components/schemas/Currency"
+ */
 export type AdminCurrenciesRes = {
   currency: Currency
 }

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

@@ -42,21 +42,7 @@ import { FeatureFlagDecorators } from "../../../../utils/feature-flag-decorators
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminCurrenciesListRes"
- *           properties:
- *             currencies:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/Currency"
- *             count:
- *               type: integer
- *               description: The total number of items available
- *             offset:
- *               type: integer
- *               description: The number of items skipped before these items
- *             limit:
- *               type: integer
- *               description: The number of items per page
  */
 export default async (req: ExtendedRequest<Currency>, res) => {
   const currencyService: CurrencyService = req.scope.resolve("currencyService")

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

@@ -48,10 +48,7 @@ import TaxInclusivePricingFeatureFlag from "../../../../loaders/feature-flags/ta
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminCurrenciesRes"
- *           properties:
- *             currency:
- *                 $ref: "#/components/schemas/Currency"
  */
 export default async (req: ExtendedRequest<Currency>, res) => {
   const code = req.params.code as string

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

@@ -61,10 +61,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminCustomerGroupsRes"
- *           properties:
- *             customer_group:
- *               $ref: "#/components/schemas/CustomerGroup"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -47,10 +47,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminCustomerGroupsRes"
- *           properties:
- *             customer_group:
- *               $ref: "#/components/schemas/CustomerGroup"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -38,19 +38,7 @@ import { EntityManager } from "typeorm"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminCustomerGroupsDeleteRes"
- *           properties:
- *             id:
- *               type: string
- *               description: The ID of the deleted customer group.
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               default: customer_group
- *             deleted:
- *               type: boolean
- *               description: Whether the customer group was deleted successfully or not.
- *               default: true
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -61,10 +61,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminCustomerGroupsRes"
- *           properties:
- *             customer_group:
- *               $ref: "#/components/schemas/CustomerGroup"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -37,21 +37,7 @@ import CustomerController from "../../../../controllers/customers"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminCustomersListRes"
- *           properties:
- *             customers:
- *               type: array
- *               items:
- *                  $ref: "#/components/schemas/Customer"
- *             count:
- *               type: integer
- *               description: The total number of items available
- *             offset:
- *               type: integer
- *               description: The number of items skipped before these items
- *             limit:
- *               type: integer
- *               description: The number of items per page
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -40,10 +40,7 @@ import { FindParams } from "../../../../types/common"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminCustomerGroupsRes"
- *           properties:
- *             customer_group:
- *               $ref: "#/components/schemas/CustomerGroup"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -56,13 +56,53 @@ export default (app) => {
 /* ************************************** */
 /* ******** EXPORT API CLIENT TYPES ***** */
 /* ************************************** */
-
+/**
+ * @schema AdminCustomerGroupsRes
+ * type: object
+ * properties:
+ *   customer_group:
+ *     $ref: "#/components/schemas/CustomerGroup"
+ */
 export type AdminCustomerGroupsRes = {
   customer_group: CustomerGroup
 }
 
+/**
+ * @schema AdminCustomerGroupsDeleteRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted customer group.
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: customer_group
+ *   deleted:
+ *     type: boolean
+ *     description: Whether the customer group was deleted successfully or not.
+ *     default: true
+ */
 export type AdminCustomerGroupsDeleteRes = DeleteResponse
 
+/**
+ * @schema AdminCustomerGroupsListRes
+ * type: object
+ * properties:
+ *   customer_groups:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/CustomerGroup"
+ *   count:
+ *     type: integer
+ *     description: The total number of items available
+ *   offset:
+ *     type: integer
+ *     description: The number of items skipped before these items
+ *   limit:
+ *     type: integer
+ *     description: The number of items per page
+ */
 export type AdminCustomerGroupsListRes = PaginatedResponse & {
   customer_groups: CustomerGroup[]
 }

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

@@ -127,21 +127,7 @@ import { Type } from "class-transformer"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminCustomerGroupsListRes"
- *           properties:
- *             customer_groups:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/CustomerGroup"
- *             count:
- *               type: integer
- *               description: The total number of items available
- *             offset:
- *               type: integer
- *               description: The number of items skipped before these items
- *             limit:
- *               type: integer
- *               description: The number of items per page
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -53,10 +53,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminCustomerGroupsRes"
- *           properties:
- *             customer_group:
- *               $ref: "#/components/schemas/CustomerGroup"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -54,10 +54,7 @@ import { EntityManager } from "typeorm"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminCustomersRes"
- *           properties:
- *             customer:
- *               $ref: "#/components/schemas/Customer"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -40,10 +40,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminCustomersRes"
- *           properties:
- *             customer:
- *               $ref: "#/components/schemas/Customer"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -1,6 +1,6 @@
 import { Router } from "express"
 import { Customer } from "../../../.."
-import { DeleteResponse, PaginatedResponse } from "../../../../types/common"
+import { PaginatedResponse } from "../../../../types/common"
 import middlewares from "../../../middlewares"
 
 const route = Router()
@@ -20,12 +20,35 @@ export default (app) => {
   return app
 }
 
+/**
+ * @schema AdminCustomersRes
+ * type: object
+ * properties:
+ *   customer:
+ *     $ref: "#/components/schemas/Customer"
+ */
 export type AdminCustomersRes = {
   customer: Customer
 }
 
-export type AdminCustomersDeleteRes = DeleteResponse
+/**
-
+ * @schema AdminCustomersListRes
+ * type: object
+ * properties:
+ *   customers:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/Customer"
+ *   count:
+ *     type: integer
+ *     description: The total number of items available
+ *   offset:
+ *     type: integer
+ *     description: The number of items skipped before these items
+ *   limit:
+ *     type: integer
+ *     description: The number of items per page
+ */
 export type AdminCustomersListRes = PaginatedResponse & {
   customers: Customer[]
 }

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

@@ -43,21 +43,7 @@ import customerController from "../../../../controllers/customers"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminCustomersListRes"
- *           properties:
- *             customers:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/Customer"
- *             count:
- *               type: integer
- *               description: The total number of items available
- *             offset:
- *               type: integer
- *               description: The number of items skipped before these items
- *             limit:
- *               type: integer
- *               description: The number of items per page
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -63,10 +63,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminCustomersRes"
- *           properties:
- *             customer:
- *               $ref: "#/components/schemas/Customer"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":