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/discounts/add-region.ts

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

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

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

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

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

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

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

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

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

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

@@ -42,22 +42,7 @@ import { FindParams } from "../../../../types/common"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             id:
- *               type: string
- *               description: The ID of the deleted DiscountCondition
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               default: discount-condition
- *             deleted:
- *               type: boolean
- *               description: Whether the discount condition was deleted successfully or not.
- *               default: true
- *             discount:
- *               description: The Discount to which the condition used to belong
- *               $ref: "#/components/schemas/Discount"
+ *           $ref: "#/components/schemas/AdminDiscountConditionsDeleteRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -220,16 +220,87 @@ export const defaultAdminDiscountConditionFields: (keyof DiscountCondition)[] =
 
 export const defaultAdminDiscountConditionRelations = ["discount_rule"]
 
+/**
+ * @schema AdminDiscountsRes
+ * type: object
+ * properties:
+ *   discount:
+ *     $ref: "#/components/schemas/Discount"
+ */
 export type AdminDiscountsRes = {
   discount: Discount
 }
 
+/**
+ * @schema AdminDiscountConditionsRes
+ * type: object
+ * properties:
+ *   discount_condition:
+ *     $ref: "#/components/schemas/DiscountCondition"
+ */
 export type AdminDiscountConditionsRes = {
   discount_condition: DiscountCondition
 }
 
+/**
+ * @schema AdminDiscountsDeleteRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted Discount
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: discount
+ *   deleted:
+ *     type: boolean
+ *     description: Whether the discount was deleted successfully or not.
+ *     default: true
+ */
 export type AdminDiscountsDeleteRes = DeleteResponse
 
+/**
+ * @schema AdminDiscountConditionsDeleteRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted DiscountCondition
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: discount-condition
+ *   deleted:
+ *     type: boolean
+ *     description: Whether the discount condition was deleted successfully or not.
+ *     default: true
+ *   discount:
+ *     description: The Discount to which the condition used to belong
+ *     $ref: "#/components/schemas/Discount"
+ */
+export type AdminDiscountConditionsDeleteRes = DeleteResponse & {
+  discount: Discount
+}
+
+/**
+ * @schema AdminDiscountsListRes
+ * type: object
+ * properties:
+ *   discounts:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/Discount"
+ *   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 AdminDiscountsListRes = PaginatedResponse & {
   discounts: Discount[]
 }

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

@@ -66,21 +66,7 @@ import { optionalBooleanMapper } from "../../../../utils/validators/is-boolean"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             discounts:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/Discount"
- *             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/AdminDiscountsListRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

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

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

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

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

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

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":

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

@@ -49,10 +49,7 @@ import { EntityManager } from "typeorm"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             gift_card:
- *               $ref: "#/components/schemas/GiftCard"
+ *           $ref: "#/components/schemas/AdminGiftCardsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
@@ -67,13 +64,16 @@ import { EntityManager } from "typeorm"
  *     $ref: "#/components/responses/500_error"
  */
 export default async (req, res) => {
-  const validatedBody: AdminPostGiftCardsReq & { balance?: number } = req.validatedBody
+  const validatedBody: AdminPostGiftCardsReq & { balance?: number } =
+    req.validatedBody
   validatedBody.balance = validatedBody.value
 
   const giftCardService: GiftCardService = req.scope.resolve("giftCardService")
   const manager: EntityManager = req.scope.resolve("manager")
   const newly = await manager.transaction(async (transactionManager) => {
-    return await giftCardService.withTransaction(transactionManager).create(validatedBody)
+    return await giftCardService
+      .withTransaction(transactionManager)
+      .create(validatedBody)
   })
 
   const giftCard = await giftCardService.retrieve(newly.id, {

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

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

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

@@ -35,10 +35,7 @@ import { defaultAdminGiftCardFields, defaultAdminGiftCardRelations } from "./"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             gift_card:
- *               $ref: "#/components/schemas/GiftCard"
+ *           $ref: "#/components/schemas/AdminGiftCardsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -2,9 +2,12 @@ import { Router } from "express"
 import "reflect-metadata"
 import { GiftCard } from "../../../.."
 import { DeleteResponse, PaginatedResponse } from "../../../../types/common"
-import middlewares, { transformQuery, transformBody } from "../../../middlewares"
+import middlewares, {
+  transformBody,
+  transformQuery,
+} from "../../../middlewares"
 import { AdminGetGiftCardsParams } from "./list-gift-cards"
-import { AdminPostGiftCardsReq } from './create-gift-card'
+import { AdminPostGiftCardsReq } from "./create-gift-card"
 
 const route = Router()
 
@@ -53,12 +56,53 @@ export const defaultAdminGiftCardFields: (keyof GiftCard)[] = [
 
 export const defaultAdminGiftCardRelations = ["region", "order"]
 
+/**
+ * @schema AdminGiftCardsRes
+ * type: object
+ * properties:
+ *   gift_card:
+ *     $ref: "#/components/schemas/GiftCard"
+ */
 export type AdminGiftCardsRes = {
   gift_card: GiftCard
 }
 
+/**
+ * @schema AdminGiftCardsDeleteRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted Gift Card
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: gift-card
+ *   deleted:
+ *     type: boolean
+ *     description: Whether the gift card was deleted successfully or not.
+ *     default: true
+ */
 export type AdminGiftCardsDeleteRes = DeleteResponse
 
+/**
+ * @schema AdminGiftCardsListRes
+ * type: object
+ * properties:
+ *   gift_cards:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/GiftCard"
+ *   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 AdminGiftCardsListRes = PaginatedResponse & {
   gift_cards: GiftCard[]
 }

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

@@ -43,21 +43,7 @@ import { isDefined } from "medusa-core-utils"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             gift_cards:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/GiftCard"
- *             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/AdminGiftCardsListRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

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

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

@@ -4,8 +4,8 @@ import InviteService from "../../../../services/invite"
 /**
  * @oas [delete] /invites/{invite_id}
  * operationId: "DeleteInvitesInvite"
- * summary: "Create an Invite"
- * description: "Creates an Invite and triggers an 'invite' created event"
+ * summary: "Delete an Invite"
+ * description: "Deletes an Invite"
  * x-authenticated: true
  * parameters:
  *   - (path) invite_id=* {string} The ID of the Invite
@@ -36,19 +36,7 @@ import InviteService from "../../../../services/invite"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             id:
- *               type: string
- *               description: The ID of the deleted Invite.
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               format: invite
- *             deleted:
- *               type: boolean
- *               description: Whether or not the Invite was deleted.
- *               default: true
+ *           $ref: "#/components/schemas/AdminInviteDeleteRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -32,8 +32,33 @@ export default (app) => {
   return app
 }
 
+/**
+ * @schema AdminInviteDeleteRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted Invite.
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: invite
+ *   deleted:
+ *     type: boolean
+ *     description: Whether or not the Invite was deleted.
+ *     default: true
+ */
 export type AdminInviteDeleteRes = DeleteResponse
 
+/**
+ * @schema AdminListInvitesRes
+ * type: object
+ * properties:
+ *   invites:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/Invite"
+ */
 export type AdminListInvitesRes = {
   invites: Invite[]
 }

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

@@ -33,12 +33,7 @@ import InviteService from "../../../../services/invite"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             invites:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/Invite"
+ *           $ref: "#/components/schemas/AdminListInvitesRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

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

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

@@ -36,19 +36,7 @@ import NoteService from "../../../../services/note"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             id:
- *               type: string
- *               description: The ID of the deleted Note.
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               default: note
- *             deleted:
- *               type: boolean
- *               description: Whether or not the Note was deleted.
- *               default: true
+ *           $ref: "#/components/schemas/AdminNotesDeleteRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -35,10 +35,7 @@ import NoteService from "../../../../services/note"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             note:
- *               $ref: "#/components/schemas/Note"
+ *           $ref: "#/components/schemas/AdminNotesRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -22,12 +22,53 @@ export default (app) => {
   return app
 }
 
+/**
+ * @schema AdminNotesRes
+ * type: object
+ * properties:
+ *   note:
+ *     $ref: "#/components/schemas/Note"
+ */
 export type AdminNotesRes = {
   note: Note
 }
 
+/**
+ * @schema AdminNotesDeleteRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted Note.
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: note
+ *   deleted:
+ *     type: boolean
+ *     description: Whether or not the Note was deleted.
+ *     default: true
+ */
 export type AdminNotesDeleteRes = DeleteResponse
 
+/**
+ * @schema AdminNotesListRes
+ * type: object
+ * properties:
+ *   notes:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/Note"
+ *   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 AdminNotesListRes = PaginatedResponse & {
   notes: Note[]
 }

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

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

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

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

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

@@ -36,10 +36,26 @@ export const defaultAdminNotificationsFields = [
   "updated_at",
 ]
 
+/**
+ * @schema AdminNotificationsListRes
+ * type: object
+ * properties:
+ *   notifications:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/Notification"
+ */
 export type AdminNotificationsListRes = {
   notifications: Notification[]
 }
 
+/**
+ * @schema AdminNotificationsRes
+ * type: object
+ * properties:
+ *   notification:
+ *     $ref: "#/components/schemas/Notification"
+ */
 export type AdminNotificationsRes = {
   notification: Notification
 }

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

@@ -54,12 +54,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             notifications:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/Notification"
+ *           $ref: "#/components/schemas/AdminNotificationsListRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

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