From 27a29ef24e5ea1ba2bc0be8ecb7dd747d4c7c65b Mon Sep 17 00:00:00 2001
From: Patrick <116003638+patrick-medusajs@users.noreply.github.com>
Date: Sun, 15 Jan 2023 14:04:26 -0500
Subject: [PATCH] chore(oas): replace response with $ref class JSDoc (Admin
 SHI-V) (#3031)

### Scope

Admin routes directories SHI to V.

### 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.

Co-authored-by: Oliver Windall Juhl <59018053+olivermrbl@users.noreply.github.com>
---
 .changeset/red-mails-sing.md                  |  5 +++
 .../create-shipping-option.ts                 |  5 +--
 .../delete-shipping-option.ts                 | 14 +------
 .../shipping-options/get-shipping-option.ts   |  5 +--
 .../routes/admin/shipping-options/index.ts    | 37 ++++++++++++++++-
 .../shipping-options/list-shipping-options.ts | 10 +----
 .../update-shipping-option.ts                 |  5 +--
 .../create-shipping-profile.ts                |  5 +--
 .../delete-shipping-profile.ts                | 14 +------
 .../shipping-profiles/get-shipping-profile.ts |  5 +--
 .../routes/admin/shipping-profiles/index.ts   | 36 +++++++++++++++-
 .../list-shipping-profiles.ts                 |  7 +---
 .../update-shipping-profile.ts                |  5 +--
 .../stock-locations/create-stock-location.ts  |  7 +---
 .../stock-locations/get-stock-location.ts     |  5 +--
 .../api/routes/admin/stock-locations/index.ts | 29 +++++++++++--
 .../stock-locations/list-stock-locations.ts   | 16 +-------
 .../stock-locations/update-stock-location.ts  |  7 +---
 .../api/routes/admin/store/add-currency.ts    |  5 +--
 .../src/api/routes/admin/store/get-store.ts   |  5 +--
 .../src/api/routes/admin/store/index.ts       | 27 +++++++++++-
 .../admin/store/list-payment-providers.ts     |  7 +---
 .../routes/admin/store/list-tax-providers.ts  |  7 +---
 .../api/routes/admin/store/remove-currency.ts |  5 +--
 .../api/routes/admin/store/update-store.ts    |  5 +--
 .../src/api/routes/admin/swaps/get-swap.ts    |  5 +--
 .../src/api/routes/admin/swaps/index.ts       | 25 +++++++++++
 .../src/api/routes/admin/swaps/list-swaps.ts  | 16 +-------
 .../admin/tax-rates/add-to-product-types.ts   |  5 +--
 .../routes/admin/tax-rates/add-to-products.ts |  5 +--
 .../tax-rates/add-to-shipping-options.ts      |  5 +--
 .../routes/admin/tax-rates/create-tax-rate.ts |  5 +--
 .../routes/admin/tax-rates/delete-tax-rate.ts | 14 +------
 .../routes/admin/tax-rates/get-tax-rate.ts    |  5 +--
 .../src/api/routes/admin/tax-rates/index.ts   | 41 +++++++++++++++++++
 .../routes/admin/tax-rates/list-tax-rates.ts  | 16 +-------
 .../tax-rates/remove-from-product-types.ts    |  5 +--
 .../admin/tax-rates/remove-from-products.ts   |  5 +--
 .../tax-rates/remove-from-shipping-options.ts |  5 +--
 .../routes/admin/tax-rates/update-tax-rate.ts |  5 +--
 .../admin/uploads/create-protected-upload.ts  | 13 +-----
 .../api/routes/admin/uploads/create-upload.ts | 12 +-----
 .../api/routes/admin/uploads/delete-upload.ts | 14 +------
 .../routes/admin/uploads/get-download-url.ts  |  6 +--
 .../src/api/routes/admin/uploads/index.ts     | 38 +++++++++++++++++
 .../src/api/routes/admin/users/create-user.ts |  5 +--
 .../src/api/routes/admin/users/delete-user.ts | 14 +------
 .../src/api/routes/admin/users/get-user.ts    |  5 +--
 .../src/api/routes/admin/users/index.ts       | 33 +++++++++++++++
 .../src/api/routes/admin/users/list-users.ts  |  7 +---
 .../api/routes/admin/users/reset-password.ts  |  5 +--
 .../src/api/routes/admin/users/update-user.ts |  5 +--
 .../src/api/routes/admin/variants/index.ts    | 18 ++++++++
 .../routes/admin/variants/list-variants.ts    | 16 +-------
 54 files changed, 329 insertions(+), 302 deletions(-)
 create mode 100644 .changeset/red-mails-sing.md

diff --git a/.changeset/red-mails-sing.md b/.changeset/red-mails-sing.md
new file mode 100644
index 0000000000..5e3700f8a8
--- /dev/null
+++ b/.changeset/red-mails-sing.md
@@ -0,0 +1,5 @@
+---
+"@medusajs/medusa": patch
+---
+
+chore(oas): replace response with $ref class JSDoc (Admin SHI-V)
diff --git a/packages/medusa/src/api/routes/admin/shipping-options/create-shipping-option.ts b/packages/medusa/src/api/routes/admin/shipping-options/create-shipping-option.ts
index 89e52110d6..2da3bbecfc 100644
--- a/packages/medusa/src/api/routes/admin/shipping-options/create-shipping-option.ts
+++ b/packages/medusa/src/api/routes/admin/shipping-options/create-shipping-option.ts
@@ -68,10 +68,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             shipping_option:
- *               $ref: "#/components/schemas/ShippingOption"
+ *           $ref: "#/components/schemas/AdminShippingOptionsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/shipping-options/delete-shipping-option.ts b/packages/medusa/src/api/routes/admin/shipping-options/delete-shipping-option.ts
index 426822d037..d9fc7b31d4 100644
--- a/packages/medusa/src/api/routes/admin/shipping-options/delete-shipping-option.ts
+++ b/packages/medusa/src/api/routes/admin/shipping-options/delete-shipping-option.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 Shipping Option.
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               default: shipping-option
- *             deleted:
- *               type: boolean
- *               description: Whether or not the items were deleted.
- *               default: true
+ *           $ref: "#/components/schemas/AdminShippingOptionsDeleteRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/shipping-options/get-shipping-option.ts b/packages/medusa/src/api/routes/admin/shipping-options/get-shipping-option.ts
index 876f6b4a66..e4316c705f 100644
--- a/packages/medusa/src/api/routes/admin/shipping-options/get-shipping-option.ts
+++ b/packages/medusa/src/api/routes/admin/shipping-options/get-shipping-option.ts
@@ -33,10 +33,7 @@
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             shipping_option:
- *               $ref: "#/components/schemas/ShippingOption"
+ *           $ref: "#/components/schemas/AdminShippingOptionsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/shipping-options/index.ts b/packages/medusa/src/api/routes/admin/shipping-options/index.ts
index 4bb16ae444..a26ce0433b 100644
--- a/packages/medusa/src/api/routes/admin/shipping-options/index.ts
+++ b/packages/medusa/src/api/routes/admin/shipping-options/index.ts
@@ -1,6 +1,6 @@
 import { Router } from "express"
 import { ShippingOption } from "../../../.."
-import { PaginatedResponse, DeleteResponse } from "../../../../types/common"
+import { DeleteResponse, PaginatedResponse } from "../../../../types/common"
 import middlewares from "../../../middlewares"
 import { FlagRouter } from "../../../../utils/flag-router"
 import TaxInclusivePricingFeatureFlag from "../../../../loaders/feature-flags/tax-inclusive-pricing"
@@ -52,14 +52,49 @@ export const defaultFields = [
 
 export const defaultRelations = ["region", "profile", "requirements"]
 
+/**
+ * @schema AdminShippingOptionsListRes
+ * type: object
+ * properties:
+ *   shipping_options:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/ShippingOption"
+ *   count:
+ *     type: integer
+ *     description: The total number of items available
+ */
 export type AdminShippingOptionsListRes = PaginatedResponse & {
   shipping_options: ShippingOption[]
 }
 
+/**
+ * @schema AdminShippingOptionsRes
+ * type: object
+ * properties:
+ *   shipping_option:
+ *     $ref: "#/components/schemas/ShippingOption"
+ */
 export type AdminShippingOptionsRes = {
   shipping_option: ShippingOption
 }
 
+/**
+ * @schema AdminShippingOptionsDeleteRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted Shipping Option.
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: shipping-option
+ *   deleted:
+ *     type: boolean
+ *     description: Whether or not the items were deleted.
+ *     default: true
+ */
 export type AdminShippingOptionsDeleteRes = DeleteResponse
 
 export * from "./create-shipping-option"
diff --git a/packages/medusa/src/api/routes/admin/shipping-options/list-shipping-options.ts b/packages/medusa/src/api/routes/admin/shipping-options/list-shipping-options.ts
index ade87c8c80..2aa7ab58cf 100644
--- a/packages/medusa/src/api/routes/admin/shipping-options/list-shipping-options.ts
+++ b/packages/medusa/src/api/routes/admin/shipping-options/list-shipping-options.ts
@@ -55,15 +55,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             shipping_options:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/ShippingOption"
- *             count:
- *               type: integer
- *               description: The total number of items available
+ *           $ref: "#/components/schemas/AdminShippingOptionsListRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/shipping-options/update-shipping-option.ts b/packages/medusa/src/api/routes/admin/shipping-options/update-shipping-option.ts
index e156ef8f67..731543b1ff 100644
--- a/packages/medusa/src/api/routes/admin/shipping-options/update-shipping-option.ts
+++ b/packages/medusa/src/api/routes/admin/shipping-options/update-shipping-option.ts
@@ -73,10 +73,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             shipping_option:
- *               $ref: "#/components/schemas/ShippingOption"
+ *           $ref: "#/components/schemas/AdminShippingOptionsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/shipping-profiles/create-shipping-profile.ts b/packages/medusa/src/api/routes/admin/shipping-profiles/create-shipping-profile.ts
index 4551719493..cc6111963b 100644
--- a/packages/medusa/src/api/routes/admin/shipping-profiles/create-shipping-profile.ts
+++ b/packages/medusa/src/api/routes/admin/shipping-profiles/create-shipping-profile.ts
@@ -47,10 +47,7 @@ import { EntityManager } from "typeorm"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             shipping_profile:
- *               $ref: "#/components/schemas/ShippingProfile"
+ *           $ref: "#/components/schemas/AdminShippingProfilesRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/shipping-profiles/delete-shipping-profile.ts b/packages/medusa/src/api/routes/admin/shipping-profiles/delete-shipping-profile.ts
index 106735d0e6..3b42f4c8eb 100644
--- a/packages/medusa/src/api/routes/admin/shipping-profiles/delete-shipping-profile.ts
+++ b/packages/medusa/src/api/routes/admin/shipping-profiles/delete-shipping-profile.ts
@@ -36,19 +36,7 @@ import { ShippingProfileService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             id:
- *               type: string
- *               description: The ID of the deleted Shipping Profile.
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               default: shipping_profile
- *             deleted:
- *               type: boolean
- *               description: Whether or not the items were deleted.
- *               default: true
+ *           $ref: "#/components/schemas/AdminDeleteShippingProfileRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/shipping-profiles/get-shipping-profile.ts b/packages/medusa/src/api/routes/admin/shipping-profiles/get-shipping-profile.ts
index 74f7edde97..aac7abe3f1 100644
--- a/packages/medusa/src/api/routes/admin/shipping-profiles/get-shipping-profile.ts
+++ b/packages/medusa/src/api/routes/admin/shipping-profiles/get-shipping-profile.ts
@@ -40,10 +40,7 @@ import { ShippingProfileService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             shipping_profile:
- *               $ref: "#/components/schemas/ShippingProfile"
+ *           $ref: "#/components/schemas/AdminShippingProfilesRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/shipping-profiles/index.ts b/packages/medusa/src/api/routes/admin/shipping-profiles/index.ts
index ae8d503966..96225d86a6 100644
--- a/packages/medusa/src/api/routes/admin/shipping-profiles/index.ts
+++ b/packages/medusa/src/api/routes/admin/shipping-profiles/index.ts
@@ -41,15 +41,47 @@ export const defaultAdminShippingProfilesFields: (keyof ShippingProfile)[] = [
   "metadata",
 ]
 
-export type AdminDeleteShippingProfileRes = DeleteResponse
-
 export const defaultAdminShippingProfilesRelations: (keyof ShippingProfile)[] =
   ["products", "shipping_options"]
 
+/**
+ * @schema AdminDeleteShippingProfileRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted Shipping Profile.
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: shipping_profile
+ *   deleted:
+ *     type: boolean
+ *     description: Whether or not the items were deleted.
+ *     default: true
+ */
+export type AdminDeleteShippingProfileRes = DeleteResponse
+
+/**
+ * @schema AdminShippingProfilesRes
+ * type: object
+ * properties:
+ *   shipping_profile:
+ *     $ref: "#/components/schemas/ShippingProfile"
+ */
 export type AdminShippingProfilesRes = {
   shipping_profile: ShippingProfile
 }
 
+/**
+ * @schema AdminShippingProfilesListRes
+ * type: object
+ * properties:
+ *   shipping_profiles:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/ShippingProfile"
+ */
 export type AdminShippingProfilesListRes = {
   shipping_profiles: ShippingProfile[]
 }
diff --git a/packages/medusa/src/api/routes/admin/shipping-profiles/list-shipping-profiles.ts b/packages/medusa/src/api/routes/admin/shipping-profiles/list-shipping-profiles.ts
index cc16e82a12..0f1876e72a 100644
--- a/packages/medusa/src/api/routes/admin/shipping-profiles/list-shipping-profiles.ts
+++ b/packages/medusa/src/api/routes/admin/shipping-profiles/list-shipping-profiles.ts
@@ -33,12 +33,7 @@ import { ShippingProfileService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             shipping_profiles:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/ShippingProfile"
+ *           $ref: "#/components/schemas/AdminShippingProfilesListRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/shipping-profiles/update-shipping-profile.ts b/packages/medusa/src/api/routes/admin/shipping-profiles/update-shipping-profile.ts
index bf00e6e754..8af222d63b 100644
--- a/packages/medusa/src/api/routes/admin/shipping-profiles/update-shipping-profile.ts
+++ b/packages/medusa/src/api/routes/admin/shipping-profiles/update-shipping-profile.ts
@@ -49,10 +49,7 @@ import { EntityManager } from "typeorm"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             shipping_profile:
- *               $ref: "#/components/schemas/ShippingProfile"
+ *           $ref: "#/components/schemas/AdminShippingProfilesRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/stock-locations/create-stock-location.ts b/packages/medusa/src/api/routes/admin/stock-locations/create-stock-location.ts
index e56a4c0d6a..511f3a7ee3 100644
--- a/packages/medusa/src/api/routes/admin/stock-locations/create-stock-location.ts
+++ b/packages/medusa/src/api/routes/admin/stock-locations/create-stock-location.ts
@@ -1,6 +1,6 @@
 import { Request, Response } from "express"
 import { Type } from "class-transformer"
-import { ValidateNested, IsOptional, IsString, IsObject } from "class-validator"
+import { IsObject, IsOptional, IsString, ValidateNested } from "class-validator"
 
 import { IStockLocationService } from "../../../../interfaces"
 import { FindParams } from "../../../../types/common"
@@ -53,10 +53,7 @@ import { FindParams } from "../../../../types/common"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             stock_location:
- *               $ref: "#/components/schemas/StockLocationDTO"
+ *           $ref: "#/components/schemas/AdminStockLocationsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/stock-locations/get-stock-location.ts b/packages/medusa/src/api/routes/admin/stock-locations/get-stock-location.ts
index b3fba0da2a..ae09a25668 100644
--- a/packages/medusa/src/api/routes/admin/stock-locations/get-stock-location.ts
+++ b/packages/medusa/src/api/routes/admin/stock-locations/get-stock-location.ts
@@ -39,10 +39,7 @@ import { FindParams } from "../../../../types/common"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             stock_location:
- *               $ref: "#/components/schemas/StockLocationDTO"
+ *           $ref: "#/components/schemas/AdminStockLocationsRes"
  */
 export default async (req: Request, res: Response) => {
   const { id } = req.params
diff --git a/packages/medusa/src/api/routes/admin/stock-locations/index.ts b/packages/medusa/src/api/routes/admin/stock-locations/index.ts
index 59e1f7328f..2994ceef93 100644
--- a/packages/medusa/src/api/routes/admin/stock-locations/index.ts
+++ b/packages/medusa/src/api/routes/admin/stock-locations/index.ts
@@ -1,6 +1,6 @@
 import { Router } from "express"
 import "reflect-metadata"
-import { DeleteResponse, PaginatedResponse } from "../../../../types/common"
+import { PaginatedResponse } from "../../../../types/common"
 import { StockLocationDTO } from "../../../../types/stock-location"
 import middlewares, {
   transformBody,
@@ -85,12 +85,35 @@ export const defaultAdminStockLocationFields: (keyof StockLocationDTO)[] = [
 
 export const defaultAdminStockLocationRelations = []
 
+/**
+ * @schema AdminStockLocationsRes
+ * type: object
+ * properties:
+ *   stock_location:
+ *     $ref: "#/components/schemas/StockLocationDTO"
+ */
 export type AdminStockLocationsRes = {
   stock_location: StockLocationDTO
 }
 
-export type AdminStockLocationsDeleteRes = DeleteResponse
-
+/**
+ * @schema AdminStockLocationsListRes
+ * type: object
+ * properties:
+ *   stock_locations:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/StockLocationDTO"
+ *   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 AdminStockLocationsListRes = PaginatedResponse & {
   stock_locations: StockLocationDTO[]
 }
diff --git a/packages/medusa/src/api/routes/admin/stock-locations/list-stock-locations.ts b/packages/medusa/src/api/routes/admin/stock-locations/list-stock-locations.ts
index 84065dad08..ef5f3eef2b 100644
--- a/packages/medusa/src/api/routes/admin/stock-locations/list-stock-locations.ts
+++ b/packages/medusa/src/api/routes/admin/stock-locations/list-stock-locations.ts
@@ -112,21 +112,7 @@ import { Request, Response } from "express"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             stock_locations:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/StockLocationDTO"
- *             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/AdminStockLocationsListRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/stock-locations/update-stock-location.ts b/packages/medusa/src/api/routes/admin/stock-locations/update-stock-location.ts
index bf0b81ce43..bba4cbc784 100644
--- a/packages/medusa/src/api/routes/admin/stock-locations/update-stock-location.ts
+++ b/packages/medusa/src/api/routes/admin/stock-locations/update-stock-location.ts
@@ -1,6 +1,6 @@
 import { Request, Response } from "express"
 import { Type } from "class-transformer"
-import { ValidateNested, IsOptional, IsString, IsObject } from "class-validator"
+import { IsObject, IsOptional, IsString, ValidateNested } from "class-validator"
 
 import { IStockLocationService } from "../../../../interfaces"
 import { FindParams } from "../../../../types/common"
@@ -53,10 +53,7 @@ import { FindParams } from "../../../../types/common"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             stock_location:
- *               $ref: "#/components/schemas/StockLocationDTO"
+ *           $ref: "#/components/schemas/AdminStockLocationsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/store/add-currency.ts b/packages/medusa/src/api/routes/admin/store/add-currency.ts
index 5b448ed3c7..573d590e71 100644
--- a/packages/medusa/src/api/routes/admin/store/add-currency.ts
+++ b/packages/medusa/src/api/routes/admin/store/add-currency.ts
@@ -44,10 +44,7 @@ import { EntityManager } from "typeorm"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             store:
- *               $ref: "#/components/schemas/Store"
+ *           $ref: "#/components/schemas/AdminStoresRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/store/get-store.ts b/packages/medusa/src/api/routes/admin/store/get-store.ts
index 6a7cba06bc..2724a261d1 100644
--- a/packages/medusa/src/api/routes/admin/store/get-store.ts
+++ b/packages/medusa/src/api/routes/admin/store/get-store.ts
@@ -42,10 +42,7 @@ import { ModulesHelper } from "../../../../utils/module-helper"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             store:
- *               $ref: "#/components/schemas/Store"
+ *           $ref: "#/components/schemas/AdminStoresRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/store/index.ts b/packages/medusa/src/api/routes/admin/store/index.ts
index 991e68aeb9..dfd6a7da90 100644
--- a/packages/medusa/src/api/routes/admin/store/index.ts
+++ b/packages/medusa/src/api/routes/admin/store/index.ts
@@ -1,5 +1,5 @@
 import { Router } from "express"
-import { Store, PaymentProvider, TaxProvider } from "./../../../../"
+import { PaymentProvider, Store, TaxProvider } from "./../../../../"
 import middlewares from "../../../middlewares"
 
 const route = Router()
@@ -29,14 +29,39 @@ export default (app) => {
   return app
 }
 
+/**
+ * @schema AdminStoresRes
+ * type: object
+ * properties:
+ *   store:
+ *     $ref: "#/components/schemas/Store"
+ */
 export type AdminStoresRes = {
   store: Store
 }
 
+/**
+ * @schema AdminTaxProvidersList
+ * type: object
+ * properties:
+ *   tax_providers:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/TaxProvider"
+ */
 export type AdminTaxProvidersList = {
   tax_providers: TaxProvider[]
 }
 
+/**
+ * @schema AdminPaymentProvidersList
+ * type: object
+ * properties:
+ *   payment_providers:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/PaymentProvider"
+ */
 export type AdminPaymentProvidersList = {
   payment_providers: PaymentProvider[]
 }
diff --git a/packages/medusa/src/api/routes/admin/store/list-payment-providers.ts b/packages/medusa/src/api/routes/admin/store/list-payment-providers.ts
index 9faa07e579..f7ffebd9e3 100644
--- a/packages/medusa/src/api/routes/admin/store/list-payment-providers.ts
+++ b/packages/medusa/src/api/routes/admin/store/list-payment-providers.ts
@@ -33,12 +33,7 @@ import { PaymentProviderService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             payment_providers:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/PaymentProvider"
+ *           $ref: "#/components/schemas/AdminPaymentProvidersList"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/store/list-tax-providers.ts b/packages/medusa/src/api/routes/admin/store/list-tax-providers.ts
index bb5cdf61b2..ba7a2cfdbb 100644
--- a/packages/medusa/src/api/routes/admin/store/list-tax-providers.ts
+++ b/packages/medusa/src/api/routes/admin/store/list-tax-providers.ts
@@ -33,12 +33,7 @@ import { TaxProviderService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             tax_providers:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/TaxProvider"
+ *           $ref: "#/components/schemas/AdminTaxProvidersList"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/store/remove-currency.ts b/packages/medusa/src/api/routes/admin/store/remove-currency.ts
index 5d39607da9..9ad9033d5b 100644
--- a/packages/medusa/src/api/routes/admin/store/remove-currency.ts
+++ b/packages/medusa/src/api/routes/admin/store/remove-currency.ts
@@ -44,10 +44,7 @@ import { EntityManager } from "typeorm"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             store:
- *               $ref: "#/components/schemas/Store"
+ *           $ref: "#/components/schemas/AdminStoresRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/store/update-store.ts b/packages/medusa/src/api/routes/admin/store/update-store.ts
index 8a5dc11a92..4b77f31c22 100644
--- a/packages/medusa/src/api/routes/admin/store/update-store.ts
+++ b/packages/medusa/src/api/routes/admin/store/update-store.ts
@@ -48,10 +48,7 @@ import { EntityManager } from "typeorm"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             store:
- *               $ref: "#/components/schemas/Store"
+ *           $ref: "#/components/schemas/AdminStoresRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/swaps/get-swap.ts b/packages/medusa/src/api/routes/admin/swaps/get-swap.ts
index 8e47f0e789..8276b95669 100644
--- a/packages/medusa/src/api/routes/admin/swaps/get-swap.ts
+++ b/packages/medusa/src/api/routes/admin/swaps/get-swap.ts
@@ -37,10 +37,7 @@ import { SwapService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             swap:
- *               $ref: "#/components/schemas/Swap"
+ *           $ref: "#/components/schemas/AdminSwapsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/swaps/index.ts b/packages/medusa/src/api/routes/admin/swaps/index.ts
index 8b866c9ac6..aaf5e2ab67 100644
--- a/packages/medusa/src/api/routes/admin/swaps/index.ts
+++ b/packages/medusa/src/api/routes/admin/swaps/index.ts
@@ -53,10 +53,35 @@ export const defaultAdminSwapFields = [
   "cart.total",
 ]
 
+/**
+ * @schema AdminSwapsListRes
+ * type: object
+ * properties:
+ *   swaps:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/Swap"
+ *   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 AdminSwapsListRes = PaginatedResponse & {
   swaps: Swap[]
 }
 
+/**
+ * @schema AdminSwapsRes
+ * type: object
+ * properties:
+ *   swap:
+ *     $ref: "#/components/schemas/Swap"
+ */
 export type AdminSwapsRes = {
   swap: Swap
 }
diff --git a/packages/medusa/src/api/routes/admin/swaps/list-swaps.ts b/packages/medusa/src/api/routes/admin/swaps/list-swaps.ts
index 2533d48a34..29ac8016c0 100644
--- a/packages/medusa/src/api/routes/admin/swaps/list-swaps.ts
+++ b/packages/medusa/src/api/routes/admin/swaps/list-swaps.ts
@@ -42,21 +42,7 @@ import { Swap } from "../../../../models"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             swaps:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/Swap"
- *             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/AdminSwapsListRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/tax-rates/add-to-product-types.ts b/packages/medusa/src/api/routes/admin/tax-rates/add-to-product-types.ts
index b7d275785a..bf3fe105f4 100644
--- a/packages/medusa/src/api/routes/admin/tax-rates/add-to-product-types.ts
+++ b/packages/medusa/src/api/routes/admin/tax-rates/add-to-product-types.ts
@@ -74,10 +74,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             tax_rate:
- *               $ref: "#/components/schemas/TaxRate"
+ *           $ref: "#/components/schemas/AdminTaxRatesRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/tax-rates/add-to-products.ts b/packages/medusa/src/api/routes/admin/tax-rates/add-to-products.ts
index 043c115f10..fdc4cffa33 100644
--- a/packages/medusa/src/api/routes/admin/tax-rates/add-to-products.ts
+++ b/packages/medusa/src/api/routes/admin/tax-rates/add-to-products.ts
@@ -74,10 +74,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             tax_rate:
- *               $ref: "#/components/schemas/TaxRate"
+ *           $ref: "#/components/schemas/AdminTaxRatesRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/tax-rates/add-to-shipping-options.ts b/packages/medusa/src/api/routes/admin/tax-rates/add-to-shipping-options.ts
index 02fcbf583f..4fda0b1980 100644
--- a/packages/medusa/src/api/routes/admin/tax-rates/add-to-shipping-options.ts
+++ b/packages/medusa/src/api/routes/admin/tax-rates/add-to-shipping-options.ts
@@ -74,10 +74,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             tax_rate:
- *               $ref: "#/components/schemas/TaxRate"
+ *           $ref: "#/components/schemas/AdminTaxRatesRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/tax-rates/create-tax-rate.ts b/packages/medusa/src/api/routes/admin/tax-rates/create-tax-rate.ts
index 46106584f0..2d3fd062bc 100644
--- a/packages/medusa/src/api/routes/admin/tax-rates/create-tax-rate.ts
+++ b/packages/medusa/src/api/routes/admin/tax-rates/create-tax-rate.ts
@@ -76,10 +76,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             tax_rate:
- *               $ref: "#/components/schemas/TaxRate"
+ *           $ref: "#/components/schemas/AdminTaxRatesRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/tax-rates/delete-tax-rate.ts b/packages/medusa/src/api/routes/admin/tax-rates/delete-tax-rate.ts
index b2cc84301d..f1a2907ad6 100644
--- a/packages/medusa/src/api/routes/admin/tax-rates/delete-tax-rate.ts
+++ b/packages/medusa/src/api/routes/admin/tax-rates/delete-tax-rate.ts
@@ -36,19 +36,7 @@ import { TaxRateService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             id:
- *               type: string
- *               description: The ID of the deleted Shipping Option.
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               default: tax-rate
- *             deleted:
- *               type: boolean
- *               description: Whether or not the items were deleted.
- *               default: true
+ *           $ref: "#/components/schemas/AdminTaxRatesDeleteRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/tax-rates/get-tax-rate.ts b/packages/medusa/src/api/routes/admin/tax-rates/get-tax-rate.ts
index 3fc0efc649..a2ee5af9e1 100644
--- a/packages/medusa/src/api/routes/admin/tax-rates/get-tax-rate.ts
+++ b/packages/medusa/src/api/routes/admin/tax-rates/get-tax-rate.ts
@@ -58,10 +58,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             tax_rate:
- *               $ref: "#/components/schemas/TaxRate"
+ *           $ref: "#/components/schemas/AdminTaxRatesRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/tax-rates/index.ts b/packages/medusa/src/api/routes/admin/tax-rates/index.ts
index 10fac4404c..56bf3459cb 100644
--- a/packages/medusa/src/api/routes/admin/tax-rates/index.ts
+++ b/packages/medusa/src/api/routes/admin/tax-rates/index.ts
@@ -96,12 +96,53 @@ export const defaultAdminTaxRatesFields: (keyof TaxRate)[] = [
   "updated_at",
 ]
 
+/**
+ * @schema AdminTaxRatesDeleteRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted Shipping Option.
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: tax-rate
+ *   deleted:
+ *     type: boolean
+ *     description: Whether or not the items were deleted.
+ *     default: true
+ */
 export type AdminTaxRatesDeleteRes = DeleteResponse
 
+/**
+ * @schema AdminTaxRatesListRes
+ * type: object
+ * properties:
+ *   tax_rates:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/TaxRate"
+ *   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 AdminTaxRatesListRes = PaginatedResponse & {
   tax_rates: TaxRate[]
 }
 
+/**
+ * @schema AdminTaxRatesRes
+ * type: object
+ * properties:
+ *   tax_rate:
+ *     $ref: "#/components/schemas/TaxRate"
+ */
 export type AdminTaxRatesRes = {
   tax_rate: TaxRate
 }
diff --git a/packages/medusa/src/api/routes/admin/tax-rates/list-tax-rates.ts b/packages/medusa/src/api/routes/admin/tax-rates/list-tax-rates.ts
index 49103a3072..c4c6e97e02 100644
--- a/packages/medusa/src/api/routes/admin/tax-rates/list-tax-rates.ts
+++ b/packages/medusa/src/api/routes/admin/tax-rates/list-tax-rates.ts
@@ -98,21 +98,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             tax_rates:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/TaxRate"
- *             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/AdminTaxRatesListRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/tax-rates/remove-from-product-types.ts b/packages/medusa/src/api/routes/admin/tax-rates/remove-from-product-types.ts
index 37091f303f..855170d430 100644
--- a/packages/medusa/src/api/routes/admin/tax-rates/remove-from-product-types.ts
+++ b/packages/medusa/src/api/routes/admin/tax-rates/remove-from-product-types.ts
@@ -74,10 +74,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             tax_rate:
- *               $ref: "#/components/schemas/TaxRate"
+ *           $ref: "#/components/schemas/AdminTaxRatesRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/tax-rates/remove-from-products.ts b/packages/medusa/src/api/routes/admin/tax-rates/remove-from-products.ts
index e2f11ff456..b882ef6879 100644
--- a/packages/medusa/src/api/routes/admin/tax-rates/remove-from-products.ts
+++ b/packages/medusa/src/api/routes/admin/tax-rates/remove-from-products.ts
@@ -74,10 +74,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             tax_rate:
- *               $ref: "#/components/schemas/TaxRate"
+ *           $ref: "#/components/schemas/AdminTaxRatesRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/tax-rates/remove-from-shipping-options.ts b/packages/medusa/src/api/routes/admin/tax-rates/remove-from-shipping-options.ts
index 6638898606..d0515de36b 100644
--- a/packages/medusa/src/api/routes/admin/tax-rates/remove-from-shipping-options.ts
+++ b/packages/medusa/src/api/routes/admin/tax-rates/remove-from-shipping-options.ts
@@ -74,10 +74,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             tax_rate:
- *               $ref: "#/components/schemas/TaxRate"
+ *           $ref: "#/components/schemas/AdminTaxRatesRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/tax-rates/update-tax-rate.ts b/packages/medusa/src/api/routes/admin/tax-rates/update-tax-rate.ts
index 83d9c93a38..06f8cc8a58 100644
--- a/packages/medusa/src/api/routes/admin/tax-rates/update-tax-rate.ts
+++ b/packages/medusa/src/api/routes/admin/tax-rates/update-tax-rate.ts
@@ -73,10 +73,7 @@ import { isDefined } from "medusa-core-utils"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             tax_rate:
- *               $ref: "#/components/schemas/TaxRate"
+ *           $ref: "#/components/schemas/AdminTaxRatesRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/uploads/create-protected-upload.ts b/packages/medusa/src/api/routes/admin/uploads/create-protected-upload.ts
index b87cffd814..4b4d01864e 100644
--- a/packages/medusa/src/api/routes/admin/uploads/create-protected-upload.ts
+++ b/packages/medusa/src/api/routes/admin/uploads/create-protected-upload.ts
@@ -46,17 +46,7 @@ import { IFileService } from "../../../../interfaces"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             uploads:
- *               type: array
- *               items:
- *                 type: object
- *                 properties:
- *                   url:
- *                     type: string
- *                     description: The URL of the uploaded file.
- *                     format: uri
+ *           $ref: "#/components/schemas/AdminUploadsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
@@ -84,6 +74,7 @@ export default async (req, res) => {
 
   res.status(200).json({ uploads: result })
 }
+
 export class IAdminPostUploadsFileReq {
   originalName: string
   path: string
diff --git a/packages/medusa/src/api/routes/admin/uploads/create-upload.ts b/packages/medusa/src/api/routes/admin/uploads/create-upload.ts
index 24850a4bcf..0a4e5975c9 100644
--- a/packages/medusa/src/api/routes/admin/uploads/create-upload.ts
+++ b/packages/medusa/src/api/routes/admin/uploads/create-upload.ts
@@ -45,17 +45,7 @@ import fs from "fs"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             uploads:
- *               type: array
- *               items:
- *                 type: object
- *                 properties:
- *                   url:
- *                     type: string
- *                     description: The URL of the uploaded file.
- *                     format: uri
+ *           $ref: "#/components/schemas/AdminUploadsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/uploads/delete-upload.ts b/packages/medusa/src/api/routes/admin/uploads/delete-upload.ts
index d8ee7adcf5..52344b4540 100644
--- a/packages/medusa/src/api/routes/admin/uploads/delete-upload.ts
+++ b/packages/medusa/src/api/routes/admin/uploads/delete-upload.ts
@@ -44,19 +44,7 @@ import { IsString } from "class-validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             id:
- *               type: string
- *               description: The file key of the upload deleted
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               default: file
- *             deleted:
- *               type: boolean
- *               description: Whether or not the items were deleted.
- *               default: true
+ *           $ref: "#/components/schemas/AdminDeleteUploadsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/uploads/get-download-url.ts b/packages/medusa/src/api/routes/admin/uploads/get-download-url.ts
index 41424954ba..65bfc6f973 100644
--- a/packages/medusa/src/api/routes/admin/uploads/get-download-url.ts
+++ b/packages/medusa/src/api/routes/admin/uploads/get-download-url.ts
@@ -45,11 +45,7 @@ import { IsString } from "class-validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             download_url:
- *               type: string
- *               description: The Download URL of the file
+ *           $ref: "#/components/schemas/AdminUploadsDownloadUrlRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/uploads/index.ts b/packages/medusa/src/api/routes/admin/uploads/index.ts
index 92391f9d4b..4766f1176c 100644
--- a/packages/medusa/src/api/routes/admin/uploads/index.ts
+++ b/packages/medusa/src/api/routes/admin/uploads/index.ts
@@ -39,12 +39,50 @@ export default (app) => {
   return app
 }
 
+/**
+ * @schema AdminUploadsRes
+ * type: object
+ * properties:
+ *   uploads:
+ *     type: array
+ *     items:
+ *       type: object
+ *       properties:
+ *         url:
+ *           type: string
+ *           description: The URL of the uploaded file.
+ *           format: uri
+ */
 export type AdminUploadsRes = {
   uploads: { url: string }[]
 }
 
+/**
+ * @schema AdminDeleteUploadsRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The file key of the upload deleted
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: file
+ *   deleted:
+ *     type: boolean
+ *     description: Whether or not the items were deleted.
+ *     default: true
+ */
 export type AdminDeleteUploadsRes = DeleteResponse
 
+/**
+ * @schema AdminUploadsDownloadUrlRes
+ * type: object
+ * properties:
+ *   download_url:
+ *     type: string
+ *     description: The Download URL of the file
+ */
 export type AdminUploadsDownloadUrlRes = {
   download_url: string
 }
diff --git a/packages/medusa/src/api/routes/admin/users/create-user.ts b/packages/medusa/src/api/routes/admin/users/create-user.ts
index 1679014106..828434c8c2 100644
--- a/packages/medusa/src/api/routes/admin/users/create-user.ts
+++ b/packages/medusa/src/api/routes/admin/users/create-user.ts
@@ -52,10 +52,7 @@ import { EntityManager } from "typeorm"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             user:
- *               $ref: "#/components/schemas/User"
+ *           $ref: "#/components/schemas/AdminUserRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/users/delete-user.ts b/packages/medusa/src/api/routes/admin/users/delete-user.ts
index b79de935e3..a37ea9b207 100644
--- a/packages/medusa/src/api/routes/admin/users/delete-user.ts
+++ b/packages/medusa/src/api/routes/admin/users/delete-user.ts
@@ -36,19 +36,7 @@ import UserService from "../../../../services/user"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             id:
- *               type: string
- *               description: The ID of the deleted user.
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               default: user
- *             deleted:
- *               type: boolean
- *               description: Whether or not the items were deleted.
- *               default: true
+ *           $ref: "#/components/schemas/AdminDeleteUserRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/users/get-user.ts b/packages/medusa/src/api/routes/admin/users/get-user.ts
index c6c1842f76..7755ba01ce 100644
--- a/packages/medusa/src/api/routes/admin/users/get-user.ts
+++ b/packages/medusa/src/api/routes/admin/users/get-user.ts
@@ -35,10 +35,7 @@ import UserService from "../../../../services/user"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             user:
- *               $ref: "#/components/schemas/User"
+ *           $ref: "#/components/schemas/AdminUserRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/users/index.ts b/packages/medusa/src/api/routes/admin/users/index.ts
index e45d3b74aa..a23722bf69 100644
--- a/packages/medusa/src/api/routes/admin/users/index.ts
+++ b/packages/medusa/src/api/routes/admin/users/index.ts
@@ -34,14 +34,47 @@ export default (app) => {
 
   return app
 }
+
+/**
+ * @schema AdminUserRes
+ * type: object
+ * properties:
+ *   user:
+ *     $ref: "#/components/schemas/User"
+ */
 export type AdminUserRes = {
   user: Omit<User, "password_hash">
 }
 
+/**
+ * @schema AdminUsersListRes
+ * type: object
+ * properties:
+ *   users:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/User"
+ */
 export type AdminUsersListRes = {
   users: Omit<User, "password_hash">[]
 }
 
+/**
+ * @schema AdminDeleteUserRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted user.
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: user
+ *   deleted:
+ *     type: boolean
+ *     description: Whether or not the items were deleted.
+ *     default: true
+ */
 export type AdminDeleteUserRes = DeleteResponse
 
 export * from "./reset-password"
diff --git a/packages/medusa/src/api/routes/admin/users/list-users.ts b/packages/medusa/src/api/routes/admin/users/list-users.ts
index 7a7d0fabff..a2a8a228c7 100644
--- a/packages/medusa/src/api/routes/admin/users/list-users.ts
+++ b/packages/medusa/src/api/routes/admin/users/list-users.ts
@@ -33,12 +33,7 @@ import UserService from "../../../../services/user"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             users:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/User"
+ *           $ref: "#/components/schemas/AdminUsersListRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/users/reset-password.ts b/packages/medusa/src/api/routes/admin/users/reset-password.ts
index ea15d734ae..b02eab1b18 100644
--- a/packages/medusa/src/api/routes/admin/users/reset-password.ts
+++ b/packages/medusa/src/api/routes/admin/users/reset-password.ts
@@ -54,10 +54,7 @@ import { EntityManager } from "typeorm"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             user:
- *               $ref: "#/components/schemas/User"
+ *           $ref: "#/components/schemas/AdminUserRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/users/update-user.ts b/packages/medusa/src/api/routes/admin/users/update-user.ts
index 86d7b2fc69..3abad8c63b 100644
--- a/packages/medusa/src/api/routes/admin/users/update-user.ts
+++ b/packages/medusa/src/api/routes/admin/users/update-user.ts
@@ -51,10 +51,7 @@ import { EntityManager } from "typeorm"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             user:
- *               $ref: "#/components/schemas/User"
+ *           $ref: "#/components/schemas/AdminUserRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":
diff --git a/packages/medusa/src/api/routes/admin/variants/index.ts b/packages/medusa/src/api/routes/admin/variants/index.ts
index 1922933470..9ac27242fe 100644
--- a/packages/medusa/src/api/routes/admin/variants/index.ts
+++ b/packages/medusa/src/api/routes/admin/variants/index.ts
@@ -49,6 +49,24 @@ export const defaultAdminVariantFields: (keyof ProductVariant)[] = [
   "metadata",
 ]
 
+/**
+ * @schema AdminVariantsListRes
+ * type: object
+ * properties:
+ *   variants:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/ProductVariant"
+ *   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 AdminVariantsListRes = PaginatedResponse & {
   variants: PricedVariant[]
 }
diff --git a/packages/medusa/src/api/routes/admin/variants/list-variants.ts b/packages/medusa/src/api/routes/admin/variants/list-variants.ts
index 30d44c97a1..9a8665907e 100644
--- a/packages/medusa/src/api/routes/admin/variants/list-variants.ts
+++ b/packages/medusa/src/api/routes/admin/variants/list-variants.ts
@@ -91,21 +91,7 @@ import { IsType } from "../../../../utils/validators/is-type"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             variants:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/ProductVariant"
- *             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/AdminVariantsListRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":