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

@@ -0,0 +1,5 @@
+---
+"@medusajs/medusa": patch
+---
+
+chore(oas): replace response with $ref class JSDoc (Admin SHI-V)

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
+ *           $ref: "#/components/schemas/AdminShippingOptionsRes"
- *           properties:
- *             shipping_option:
- *               $ref: "#/components/schemas/ShippingOption"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminShippingOptionsDeleteRes"
- *           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
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/shipping-options/get-shipping-option.ts

@@ -33,10 +33,7 @@
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminShippingOptionsRes"
- *           properties:
- *             shipping_option:
- *               $ref: "#/components/schemas/ShippingOption"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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"

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
+ *           $ref: "#/components/schemas/AdminShippingOptionsListRes"
- *           properties:
- *             shipping_options:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/ShippingOption"
- *             count:
- *               type: integer
- *               description: The total number of items available
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminShippingOptionsRes"
- *           properties:
- *             shipping_option:
- *               $ref: "#/components/schemas/ShippingOption"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminShippingProfilesRes"
- *           properties:
- *             shipping_profile:
- *               $ref: "#/components/schemas/ShippingProfile"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminDeleteShippingProfileRes"
- *           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
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminShippingProfilesRes"
- *           properties:
- *             shipping_profile:
- *               $ref: "#/components/schemas/ShippingProfile"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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[]
 }

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
+ *           $ref: "#/components/schemas/AdminShippingProfilesListRes"
- *           properties:
- *             shipping_profiles:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/ShippingProfile"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminShippingProfilesRes"
- *           properties:
- *             shipping_profile:
- *               $ref: "#/components/schemas/ShippingProfile"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminStockLocationsRes"
- *           properties:
- *             stock_location:
- *               $ref: "#/components/schemas/StockLocationDTO"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminStockLocationsRes"
- *           properties:
- *             stock_location:
- *               $ref: "#/components/schemas/StockLocationDTO"
  */
 export default async (req: Request, res: Response) => {
   const { id } = req.params

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[]
 }

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
+ *           $ref: "#/components/schemas/AdminStockLocationsListRes"
- *           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
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminStockLocationsRes"
- *           properties:
- *             stock_location:
- *               $ref: "#/components/schemas/StockLocationDTO"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/store/add-currency.ts

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

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
+ *           $ref: "#/components/schemas/AdminStoresRes"
- *           properties:
- *             store:
- *               $ref: "#/components/schemas/Store"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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[]
 }

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
+ *           $ref: "#/components/schemas/AdminPaymentProvidersList"
- *           properties:
- *             payment_providers:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/PaymentProvider"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminTaxProvidersList"
- *           properties:
- *             tax_providers:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/TaxProvider"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/store/remove-currency.ts

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

packages/medusa/src/api/routes/admin/store/update-store.ts

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

packages/medusa/src/api/routes/admin/swaps/get-swap.ts

@@ -37,10 +37,7 @@ import { SwapService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminSwapsRes"
- *           properties:
- *             swap:
- *               $ref: "#/components/schemas/Swap"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
 }

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

@@ -42,21 +42,7 @@ import { Swap } from "../../../../models"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminSwapsListRes"
- *           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
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminTaxRatesRes"
- *           properties:
- *             tax_rate:
- *               $ref: "#/components/schemas/TaxRate"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminTaxRatesRes"
- *           properties:
- *             tax_rate:
- *               $ref: "#/components/schemas/TaxRate"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminTaxRatesRes"
- *           properties:
- *             tax_rate:
- *               $ref: "#/components/schemas/TaxRate"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminTaxRatesRes"
- *           properties:
- *             tax_rate:
- *               $ref: "#/components/schemas/TaxRate"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminTaxRatesDeleteRes"
- *           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
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminTaxRatesRes"
- *           properties:
- *             tax_rate:
- *               $ref: "#/components/schemas/TaxRate"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
 }

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
+ *           $ref: "#/components/schemas/AdminTaxRatesListRes"
- *           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
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminTaxRatesRes"
- *           properties:
- *             tax_rate:
- *               $ref: "#/components/schemas/TaxRate"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminTaxRatesRes"
- *           properties:
- *             tax_rate:
- *               $ref: "#/components/schemas/TaxRate"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminTaxRatesRes"
- *           properties:
- *             tax_rate:
- *               $ref: "#/components/schemas/TaxRate"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminTaxRatesRes"
- *           properties:
- *             tax_rate:
- *               $ref: "#/components/schemas/TaxRate"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminUploadsRes"
- *           properties:
- *             uploads:
- *               type: array
- *               items:
- *                 type: object
- *                 properties:
- *                   url:
- *                     type: string
- *                     description: The URL of the uploaded file.
- *                     format: uri
  *   "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

packages/medusa/src/api/routes/admin/uploads/create-upload.ts

@@ -45,17 +45,7 @@ import fs from "fs"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminUploadsRes"
- *           properties:
- *             uploads:
- *               type: array
- *               items:
- *                 type: object
- *                 properties:
- *                   url:
- *                     type: string
- *                     description: The URL of the uploaded file.
- *                     format: uri
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminDeleteUploadsRes"
- *           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
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminUploadsDownloadUrlRes"
- *           properties:
- *             download_url:
- *               type: string
- *               description: The Download URL of the file
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
 }

packages/medusa/src/api/routes/admin/users/create-user.ts

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

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
+ *           $ref: "#/components/schemas/AdminDeleteUserRes"
- *           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
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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
+ *           $ref: "#/components/schemas/AdminUserRes"
- *           properties:
- *             user:
- *               $ref: "#/components/schemas/User"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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"

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
+ *           $ref: "#/components/schemas/AdminUsersListRes"
- *           properties:
- *             users:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/User"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/users/reset-password.ts

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

packages/medusa/src/api/routes/admin/users/update-user.ts

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

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[]
 }

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
+ *           $ref: "#/components/schemas/AdminVariantsListRes"
- *           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
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":