chore(oas): replace response with $ref class JSDoc (Admin D-N) (#3015)

### Scope

Admin routes directories D to N.

### 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/draft-orders/create-draft-order.ts

@@ -92,10 +92,7 @@ import { IsType } from "../../../../utils/validators/is-type"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             draft_order:
- *               $ref: "#/components/schemas/DraftOrder"
+ *           $ref: "#/components/schemas/AdminDraftOrdersRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

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

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

@@ -1,5 +1,6 @@
 import { DraftOrderService } from "../../../../services"
 import { EntityManager } from "typeorm"
+
 /**
  * @oas [delete] /draft-orders/{id}
  * operationId: DeleteDraftOrdersDraftOrder
@@ -35,19 +36,7 @@ import { EntityManager } from "typeorm"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             id:
- *               type: string
- *               description: The ID of the deleted Draft Order.
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               default: draft-order
- *             deleted:
- *               type: boolean
- *               description: Whether the draft order was deleted successfully or not.
- *               default: true
+ *           $ref: "#/components/schemas/AdminDraftOrdersDeleteRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

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

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

@@ -43,10 +43,7 @@ import { DraftOrder } from "../../../.."
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             draft_order:
- *               $ref: "#/components/schemas/DraftOrder"
+ *           $ref: "#/components/schemas/AdminDraftOrdersRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -91,16 +91,64 @@ export const defaultAdminDraftOrdersFields: (keyof DraftOrder)[] = [
   "no_notification_order",
 ]
 
+/**
+ * @schema AdminPostDraftOrdersDraftOrderRegisterPaymentRes
+ * type: object
+ * properties:
+ *   order:
+ *     $ref: "#/components/schemas/Order"
+ */
 export type AdminPostDraftOrdersDraftOrderRegisterPaymentRes = {
   order: Order
 }
 
+/**
+ * @schema AdminDraftOrdersRes
+ * type: object
+ * properties:
+ *   draft_order:
+ *     $ref: "#/components/schemas/DraftOrder"
+ */
 export type AdminDraftOrdersRes = {
   draft_order: DraftOrder
 }
 
+/**
+ * @schema AdminDraftOrdersDeleteRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted Draft Order.
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: draft-order
+ *   deleted:
+ *     type: boolean
+ *     description: Whether the draft order was deleted successfully or not.
+ *     default: true
+ */
 export type AdminDraftOrdersDeleteRes = DeleteResponse
 
+/**
+ * @schema AdminDraftOrdersListRes
+ * type: object
+ * properties:
+ *   draft_orders:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/DraftOrder"
+ *   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 AdminDraftOrdersListRes = PaginatedResponse & {
   draft_orders: DraftOrder[]
 }

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

@@ -48,21 +48,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             draft_orders:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/DraftOrder"
- *             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
+ *           $ref: "#/components/schemas/AdminDraftOrdersListRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

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

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

@@ -66,10 +66,7 @@ import { IsType } from "../../../../utils/validators/is-type"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             draft_order:
- *               $ref: "#/components/schemas/DraftOrder"
+ *           $ref: "#/components/schemas/AdminDraftOrdersRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

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