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>
2023-01-15 14:04:26 -05:00
parent 1547dd8143
commit 27a29ef24e
54 changed files with 329 additions and 302 deletions
--- a/.changeset/red-mails-sing.md
+++ b/.changeset/red-mails-sing.md
@@ -0,0 +1,5 @@
+---
+"@medusajs/medusa": patch
+---
+
+chore(oas): replace response with $ref class JSDoc (Admin SHI-V)
--- 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":
--- 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":
--- 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":
--- 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"
--- 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":
--- 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":
--- 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":
--- 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":
--- 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":
--- 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[]
 }
--- 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":
--- 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":
--- 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":
--- 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
--- 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[]
 }
--- 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":
--- 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":
--- 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":
--- 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":
--- 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[]
 }
--- 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":
--- 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":
--- 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":
--- 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":
--- 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":
--- 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
 }
--- 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":
--- 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":
--- 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":
--- 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":
--- 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":
--- 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":
--- 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":
--- 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
 }
--- 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":
--- 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":
--- 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":
--- 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":
--- 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":
--- 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
--- 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":
--- 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":
--- 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":
--- 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
 }
--- 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":
--- 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":
--- 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":
--- 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"
--- 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":
--- 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":
--- 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":
--- 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[]
 }
--- 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":