chore(oas): replace response with $ref class JSDoc (Admin O-PRI) (#3018)

### Scope

Admin routes directories O to PRI.

### What

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

### Why

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

### How

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

### Test

- Ran OAS validator.
- Ran docs build script.

Expect no visible changes to the documentation.

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

@@ -53,10 +53,7 @@ import {
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminOrderEditsRes"
- *           properties:
- *             order_edit:
- *               $ref: "#/components/schemas/OrderEdit"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -3,7 +3,7 @@ import { EntityManager } from "typeorm"
 import { OrderEditService } from "../../../../services"
 import {
   defaultOrderEditFields,
-  defaultOrderEditRelations
+  defaultOrderEditRelations,
 } from "../../../../types/order-edit"
 
 /**
@@ -41,10 +41,7 @@ import {
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminOrderEditsRes"
- *           properties:
- *             order_edit:
- *               $ref: "#/components/schemas/OrderEdit"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -3,7 +3,7 @@ import { EntityManager } from "typeorm"
 import { OrderEditService } from "../../../../services"
 import {
   defaultOrderEditFields,
-  defaultOrderEditRelations
+  defaultOrderEditRelations,
 } from "../../../../types/order-edit"
 
 /**
@@ -41,10 +41,7 @@ import {
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminOrderEditsRes"
- *           properties:
- *             order_edit:
- *               $ref: "#/components/schemas/OrderEdit"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -4,7 +4,7 @@ import { EntityManager } from "typeorm"
 import { OrderEditService } from "../../../../services"
 import {
   defaultOrderEditFields,
-  defaultOrderEditRelations
+  defaultOrderEditRelations,
 } from "../../../../types/order-edit"
 
 /**
@@ -47,10 +47,7 @@ import {
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminOrderEditsRes"
- *           properties:
- *             order_edit:
- *               $ref: "#/components/schemas/OrderEdit"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -42,10 +42,7 @@ import {
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminOrderEditsRes"
- *           properties:
- *             order_edit:
- *               $ref: "#/components/schemas/OrderEdit"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -37,19 +37,7 @@ import { OrderEditService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminOrderEditItemChangeDeleteRes"
- *           properties:
- *             id:
- *               type: string
- *               description: The ID of the deleted Order Edit Item Change.
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               format: item_change
- *             deleted:
- *               type: boolean
- *               description: Whether or not the Order Edit Item Change was deleted.
- *               default: true
  *   "400":
  *     $ref: "#/components/responses/400_error"
  */

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

@@ -36,19 +36,7 @@ import { OrderEditService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminOrderEditDeleteRes"
- *           properties:
- *             id:
- *               type: string
- *               description: The ID of the deleted Order Edit.
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               format: order_edit
- *             deleted:
- *               type: boolean
- *               description: Whether or not the Order Edit was deleted.
- *               default: true
  *   "400":
  *     $ref: "#/components/responses/400_error"
  */

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

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

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

@@ -98,13 +98,73 @@ export default (app) => {
   return app
 }
 
+/**
+ * @schema AdminOrderEditsRes
+ * type: object
+ * properties:
+ *   order_edit:
+ *     $ref: "#/components/schemas/OrderEdit"
+ */
 export type AdminOrderEditsRes = {
   order_edit: OrderEdit
 }
+
+/**
+ * @schema AdminOrderEditsListRes
+ * type: object
+ * properties:
+ *   order_edits:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/OrderEdit"
+ *   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 AdminOrderEditsListRes = PaginatedResponse & {
   order_edits: OrderEdit[]
 }
+
+/**
+ * @schema AdminOrderEditDeleteRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted Order Edit.
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: order_edit
+ *   deleted:
+ *     type: boolean
+ *     description: Whether or not the Order Edit was deleted.
+ *     default: true
+ */
 export type AdminOrderEditDeleteRes = DeleteResponse
+
+/**
+ * @schema AdminOrderEditItemChangeDeleteRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted Order Edit Item Change.
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: item_change
+ *   deleted:
+ *     type: boolean
+ *     description: Whether or not the Order Edit Item Change was deleted.
+ *     default: true
+ */
 export type AdminOrderEditItemChangeDeleteRes = {
   id: string
   object: "item_change"

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

@@ -43,20 +43,7 @@ import { IsOptional, IsString } from "class-validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminOrderEditsListRes"
- *           properties:
- *             order_edits:
- *               type: array
- *               $ref: "#/components/schemas/OrderEdit"
- *             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/order-edits/request-confirmation.ts

@@ -4,11 +4,11 @@ import { PaymentCollectionType } from "../../../../models"
 import {
   OrderEditService,
   OrderService,
-  PaymentCollectionService
+  PaymentCollectionService,
 } from "../../../../services"
 import {
   defaultOrderEditFields,
-  defaultOrderEditRelations
+  defaultOrderEditRelations,
 } from "../../../../types/order-edit"
 
 /**
@@ -46,10 +46,7 @@ import {
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminOrderEditsRes"
- *           properties:
- *             order_edit:
- *               $ref: "#/components/schemas/OrderEdit"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -52,10 +52,7 @@ import {
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminOrderEditsRes"
- *           properties:
- *             order_edit:
- *               $ref: "#/components/schemas/OrderEdit"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -54,10 +54,7 @@ import {
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminOrderEditsRes"
- *           properties:
- *             order_edit:
- *               $ref: "#/components/schemas/OrderEdit"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/orders/add-shipping-method.ts

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

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

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

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

@@ -40,10 +40,7 @@ import { MedusaError } from "medusa-core-utils"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminOrdersRes"
- *           properties:
- *             order:
- *               $ref: "#/components/schemas/Order"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -45,10 +45,7 @@ import { MedusaError } from "medusa-core-utils"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminOrdersRes"
- *           properties:
- *             order:
- *               $ref: "#/components/schemas/Order"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -45,10 +45,7 @@ import { MedusaError } from "medusa-core-utils"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminOrdersRes"
- *           properties:
- *             order:
- *               $ref: "#/components/schemas/Order"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -45,10 +45,7 @@ import { Fulfillment } from "../../../../models"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminOrdersRes"
- *           properties:
- *             order:
- *               $ref: "#/components/schemas/Order"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

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

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

@@ -40,10 +40,7 @@ import { MedusaError } from "medusa-core-utils"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminOrdersRes"
- *           properties:
- *             order:
- *               $ref: "#/components/schemas/Order"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

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

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

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

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

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

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

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

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

@@ -76,10 +76,7 @@ import { Fulfillment, LineItem } from "../../../../models"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminOrdersRes"
- *           properties:
- *             order:
- *               $ref: "#/components/schemas/Order"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

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

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

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

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

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

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

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

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

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

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

@@ -35,10 +35,7 @@ import { OrderService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminOrdersRes"
- *           properties:
- *             order:
- *               $ref: "#/components/schemas/Order"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -1,11 +1,7 @@
 import { Router } from "express"
 import "reflect-metadata"
 import { Order } from "../../../.."
-import {
+import { FindParams, PaginatedResponse } from "../../../../types/common"
-  DeleteResponse,
-  FindParams,
-  PaginatedResponse
-} from "../../../../types/common"
 import { FlagRouter } from "../../../../utils/flag-router"
 import middlewares, { transformQuery } from "../../../middlewares"
 import { AdminGetOrdersParams } from "./list-orders"
@@ -230,12 +226,35 @@ export default (app, featureFlagRouter: FlagRouter) => {
   return app
 }
 
+/**
+ * @schema AdminOrdersRes
+ * type: object
+ * properties:
+ *   order:
+ *     $ref: "#/components/schemas/Order"
+ */
 export type AdminOrdersRes = {
   order: Order
 }
 
-export type AdminDeleteRes = DeleteResponse
+/**
-
+ * @schema AdminOrdersListRes
+ * type: object
+ * properties:
+ *   orders:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/Order"
+ *   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 AdminOrdersListRes = PaginatedResponse & {
   orders: Order[]
 }
@@ -361,4 +380,3 @@ export * from "./refund-payment"
 export * from "./request-return"
 export * from "./update-claim"
 export * from "./update-order"
-

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

@@ -180,21 +180,7 @@ import { pick } from "lodash"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminOrdersListRes"
- *           properties:
- *             orders:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/Order"
- *             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/orders/process-swap-payment.ts

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

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

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

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

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

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

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

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

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

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

@@ -35,19 +35,7 @@ import { PaymentCollectionService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminPaymentCollectionDeleteRes"
- *           properties:
- *             id:
- *               type: string
- *               description: The ID of the deleted Payment Collection.
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               format: payment_collection
- *             deleted:
- *               type: boolean
- *               description: Whether or not the Payment Collection was deleted.
- *               default: true
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

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

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

@@ -62,9 +62,33 @@ export const defaulPaymentCollectionRelations = [
   "payments",
 ]
 
+/**
+ * @schema AdminPaymentCollectionsRes
+ * type: object
+ * properties:
+ *   payment_collection:
+ *     $ref: "#/components/schemas/PaymentCollection"
+ */
 export type AdminPaymentCollectionsRes = {
   payment_collection: PaymentCollection
 }
+
+/**
+ * @schema AdminPaymentCollectionDeleteRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted Payment Collection.
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: payment_collection
+ *   deleted:
+ *     type: boolean
+ *     description: Whether or not the Payment Collection was deleted.
+ *     default: true
+ */
 export type AdminPaymentCollectionDeleteRes = {
   id: string
   object: "payment_collection"

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

@@ -36,10 +36,7 @@ import { PaymentCollectionService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminPaymentCollectionsRes"
- *           properties:
- *             payment_collection:
- *               $ref: "#/components/schemas/PaymentCollection"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -49,10 +49,7 @@ import { PaymentCollectionService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminPaymentCollectionsRes"
- *           properties:
- *             payment_collection:
- *               $ref: "#/components/schemas/PaymentCollection"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -35,10 +35,7 @@ import { PaymentService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminPaymentRes"
- *           properties:
- *             payment:
- *               $ref: "#/components/schemas/Payment"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

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

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

@@ -52,10 +52,24 @@ export const defaultPaymentFields = [
   "metadata",
 ]
 
+/**
+ * @schema AdminPaymentRes
+ * type: object
+ * properties:
+ *   payment:
+ *     $ref: "#/components/schemas/Payment"
+ */
 export type AdminPaymentRes = {
   payment: Payment
 }
 
+/**
+ * @schema AdminRefundRes
+ * type: object
+ * properties:
+ *   refund:
+ *     $ref: "#/components/schemas/Refund"
+ */
 export type AdminRefundRes = {
   refund: Refund
 }

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

@@ -59,10 +59,7 @@ import { PaymentService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminRefundRes"
- *           properties:
- *             refund:
- *               $ref: "#/components/schemas/Refund"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

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

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

@@ -83,10 +83,7 @@ import { FeatureFlagDecorators } from "../../../../utils/feature-flag-decorators
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminPriceListRes"
- *           properties:
- *             price_list:
- *               $ref: "#/components/schemas/PriceList"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -36,19 +36,7 @@ import PriceListService from "../../../../services/price-list"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminPriceListDeleteRes"
- *           properties:
- *             id:
- *               type: string
- *               description: The ID of the deleted Price List.
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               default: price-list
- *             deleted:
- *               type: boolean
- *               description: Whether or not the items were deleted.
- *               default: true
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -54,21 +54,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminPriceListDeleteBatchRes"
- *           properties:
- *             ids:
- *               type: array
- *               items:
- *                 type: string
- *                 description: The IDs of the deleted Money Amounts (Prices).
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               default: money-amount
- *             deleted:
- *               type: boolean
- *               description: Whether or not the items were deleted.
- *               default: true
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -37,21 +37,7 @@ import PriceListService from "../../../../services/price-list"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminPriceListDeleteProductPricesRes"
- *           properties:
- *              ids:
- *               type: array
- *               description: The price ids that have been deleted.
- *               items:
- *                 type: string
- *              object:
- *                type: string
- *                description: The type of the object that was deleted.
- *                default: money-amount
- *              deleted:
- *                type: boolean
- *                description: Whether or not the items were deleted.
- *                default: true
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -37,21 +37,7 @@ import PriceListService from "../../../../services/price-list"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminPriceListDeleteVariantPricesRes"
- *           properties:
- *              ids:
- *               type: array
- *               description: The price ids that have been deleted.
- *               items:
- *                 type: string
- *              object:
- *                type: string
- *                description: The type of the object that was deleted.
- *                default: money-amount
- *              deleted:
- *                type: boolean
- *                description: Whether or not the items were deleted.
- *                default: true
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -38,10 +38,7 @@ import PriceListService from "../../../../services/price-list"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminPriceListRes"
- *           properties:
- *             price_list:
- *               $ref: "#/components/schemas/PriceList"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -1,10 +1,10 @@
 import { Router } from "express"
 import "reflect-metadata"
-import { PriceList } from "../../../.."
+import { PriceList, Product } from "../../../.."
 import { DeleteResponse, PaginatedResponse } from "../../../../types/common"
 import middlewares, {
-  transformQuery,
   transformBody,
+  transformQuery,
 } from "../../../middlewares"
 import { AdminGetPriceListPaginationParams } from "./list-price-lists"
 import { AdminGetPriceListsPriceListProductsParams } from "./list-price-list-products"
@@ -93,25 +93,143 @@ export const defaultAdminPriceListFields = [
 
 export const defaultAdminPriceListRelations = ["prices", "customer_groups"]
 
+/**
+ * @schema AdminPriceListRes
+ * type: object
+ * properties:
+ *   price_list:
+ *     $ref: "#/components/schemas/PriceList"
+ */
 export type AdminPriceListRes = {
   price_list: PriceList
 }
 
+/**
+ * @schema AdminPriceListDeleteBatchRes
+ * type: object
+ * properties:
+ *   ids:
+ *     type: array
+ *     items:
+ *       type: string
+ *       description: The IDs of the deleted Money Amounts (Prices).
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: money-amount
+ *   deleted:
+ *     type: boolean
+ *     description: Whether or not the items were deleted.
+ *     default: true
+ */
 export type AdminPriceListDeleteBatchRes = {
   ids: string[]
   deleted: boolean
   object: string
 }
 
+/**
+ * @schema AdminPriceListDeleteProductPricesRes
+ * type: object
+ * properties:
+ *    ids:
+ *     type: array
+ *     description: The price ids that have been deleted.
+ *     items:
+ *       type: string
+ *    object:
+ *      type: string
+ *      description: The type of the object that was deleted.
+ *      default: money-amount
+ *    deleted:
+ *      type: boolean
+ *      description: Whether or not the items were deleted.
+ *      default: true
+ */
 export type AdminPriceListDeleteProductPricesRes = AdminPriceListDeleteBatchRes
+
+/**
+ * @schema AdminPriceListDeleteVariantPricesRes
+ * type: object
+ * properties:
+ *    ids:
+ *     type: array
+ *     description: The price ids that have been deleted.
+ *     items:
+ *       type: string
+ *    object:
+ *      type: string
+ *      description: The type of the object that was deleted.
+ *      default: money-amount
+ *    deleted:
+ *      type: boolean
+ *      description: Whether or not the items were deleted.
+ *      default: true
+ */
 export type AdminPriceListDeleteVariantPricesRes = AdminPriceListDeleteBatchRes
 
+/**
+ * @schema AdminPriceListDeleteRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted Price List.
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: price-list
+ *   deleted:
+ *     type: boolean
+ *     description: Whether or not the items were deleted.
+ *     default: true
+ */
 export type AdminPriceListDeleteRes = DeleteResponse
 
+/**
+ * @schema AdminPriceListsListRes
+ * type: object
+ * properties:
+ *   price_lists:
+ *    type: array
+ *    items:
+ *      $ref: "#/components/schemas/PriceList"
+ *   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 AdminPriceListsListRes = PaginatedResponse & {
   price_lists: PriceList[]
 }
 
+/**
+ * @schema AdminPriceListsProductsListRes
+ * type: object
+ * properties:
+ *   products:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/Product"
+ *   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 AdminPriceListsProductsListRes = PaginatedResponse & {
+  products: Product[]
+}
+
 export * from "./add-prices-batch"
 export * from "./create-price-list"
 export * from "./delete-price-list"

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

@@ -160,21 +160,7 @@ import { isDefined } from "medusa-core-utils"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminPriceListsProductsListRes"
- *           properties:
- *             products:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/Product"
- *             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/price-lists/list-price-lists.ts

@@ -141,21 +141,7 @@ import { Type } from "class-transformer"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminPriceListsListRes"
- *           properties:
- *             price_lists:
- *              type: array
- *              items:
- *                $ref: "#/components/schemas/PriceList"
- *             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/price-lists/update-price-list.ts

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