chore(oas): replace response with $ref class JSDoc (Admin PR0-SAL) (#3030)

### Scope

Admin routes directories PRO to SAL.

### 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/quiet-peas-compete.md

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

.changeset/silent-pants-doubt.md

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

packages/medusa/src/api/routes/admin/product-tags/index.ts

@@ -31,12 +31,26 @@ export const defaultAdminProductTagsFields = [
 ]
 export const defaultAdminProductTagsRelations = []
 
+/**
+ * @schema AdminProductTagsListRes
+ * type: object
+ * properties:
+ *   product_tags:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/ProductTag"
+ *   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 AdminProductTagsListRes = PaginatedResponse & {
   product_tags: ProductTag[]
 }
 
-export type AdminProductTagsRes = {
-  product_tag: ProductTag
-}
-
 export * from "./list-product-tags"

packages/medusa/src/api/routes/admin/product-tags/list-product-tags.ts

@@ -110,19 +110,7 @@ import { Request, Response } from "express"
  *    content:
  *      application/json:
  *        schema:
- *          type: object
+ *          $ref: "#/components/schemas/AdminProductTagsListRes"
- *          properties:
- *            product_tags:
- *              $ref: "#/components/schemas/ProductTag"
- *            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/product-types/index.ts

@@ -31,12 +31,26 @@ export const defaultAdminProductTypeFields = [
 ]
 export const defaultAdminProductTypeRelations = []
 
+/**
+ * @schema AdminProductTypesListRes
+ * type: object
+ * properties:
+ *   product_types:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/ProductType"
+ *   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 AdminProductTypesListRes = PaginatedResponse & {
   product_types: ProductType[]
 }
 
-export type AdminProductTypesRes = {
-  product_type: ProductType
-}
-
 export * from "./list-product-types"

packages/medusa/src/api/routes/admin/product-types/list-product-types.ts

@@ -109,19 +109,7 @@ import ProductTypeService from "../../../../services/product-type"
  *    content:
  *      application/json:
  *        schema:
- *          type: object
+ *          $ref: "#/components/schemas/AdminProductTypesListRes"
- *          properties:
- *            product_types:
- *              $ref: "#/components/schemas/ProductType"
- *            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/products/add-option.ts

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

packages/medusa/src/api/routes/admin/products/create-product.ts

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

packages/medusa/src/api/routes/admin/products/create-variant.ts

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

packages/medusa/src/api/routes/admin/products/delete-option.ts

@@ -39,21 +39,7 @@ import { ProductService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminProductsDeleteOptionRes"
- *           properties:
- *             option_id:
- *               type: string
- *               description: The ID of the deleted Product Option
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               default: option
- *             deleted:
- *               type: boolean
- *               description: Whether or not the items were deleted.
- *               default: true
- *             product:
- *               $ref: "#/components/schemas/Product"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/products/delete-product.ts

@@ -36,19 +36,7 @@ import { ProductService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminProductsDeleteRes"
- *           properties:
- *             id:
- *               type: string
- *               description: The ID of the deleted Product.
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               default: product
- *             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/products/delete-variant.ts

@@ -43,21 +43,7 @@ import { EntityManager } from "typeorm"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminProductsDeleteVariantRes"
- *           properties:
- *             variant_id:
- *               type: string
- *               description: The ID of the deleted Product Variant.
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               default: variant
- *             deleted:
- *               type: boolean
- *               description: Whether or not the items were deleted.
- *               default: true
- *             product:
- *               $ref: "#/components/schemas/Product"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/products/get-product.ts

@@ -35,10 +35,7 @@ import { PricingService, ProductService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminProductsRes"
- *           properties:
- *             product:
- *               $ref: "#/components/schemas/Product"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -1,6 +1,6 @@
 import { Router } from "express"
 import "reflect-metadata"
-import { Product, ProductTag, ProductType } from "../../../.."
+import { Product, ProductTag, ProductType, ProductVariant } from "../../../.."
 import { FindParams, PaginatedResponse } from "../../../../types/common"
 import { PricedProduct } from "../../../../types/pricing"
 import { FlagRouter } from "../../../../utils/flag-router"
@@ -132,6 +132,24 @@ export const defaultAdminProductFields: (keyof Product)[] = [
 
 export const defaultAdminGetProductsVariantsFields = ["id", "product_id"]
 
+/**
+ * @schema AdminProductsDeleteOptionRes
+ * type: object
+ * properties:
+ *   option_id:
+ *     type: string
+ *     description: The ID of the deleted Product Option
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: option
+ *   deleted:
+ *     type: boolean
+ *     description: Whether or not the items were deleted.
+ *     default: true
+ *   product:
+ *     $ref: "#/components/schemas/Product"
+ */
 export type AdminProductsDeleteOptionRes = {
   option_id: string
   object: "option"
@@ -139,6 +157,24 @@ export type AdminProductsDeleteOptionRes = {
   product: Product
 }
 
+/**
+ * @schema AdminProductsDeleteVariantRes
+ * type: object
+ * properties:
+ *   variant_id:
+ *     type: string
+ *     description: The ID of the deleted Product Variant.
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: product-variant
+ *   deleted:
+ *     type: boolean
+ *     description: Whether or not the items were deleted.
+ *     default: true
+ *   product:
+ *     $ref: "#/components/schemas/Product"
+ */
 export type AdminProductsDeleteVariantRes = {
   variant_id: string
   object: "product-variant"
@@ -146,24 +182,118 @@ export type AdminProductsDeleteVariantRes = {
   product: Product
 }
 
+/**
+ * @schema AdminProductsDeleteRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted Product.
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: product
+ *   deleted:
+ *     type: boolean
+ *     description: Whether or not the items were deleted.
+ *     default: true
+ */
 export type AdminProductsDeleteRes = {
   id: string
   object: "product"
   deleted: boolean
 }
 
+/**
+ * @schema AdminProductsListRes
+ * type: object
+ * properties:
+ *   products:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/Product"
+ *   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 AdminProductsListRes = PaginatedResponse & {
   products: (PricedProduct | Product)[]
 }
 
+/**
+ * @schema AdminProductsListVariantsRes
+ * 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 AdminProductsListVariantsRes = PaginatedResponse & {
+  variants: ProductVariant[]
+}
+
+/**
+ * @schema AdminProductsListTypesRes
+ * type: object
+ * properties:
+ *   types:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/ProductType"
+ */
 export type AdminProductsListTypesRes = {
   types: ProductType[]
 }
 
+/**
+ * @schema AdminProductsListTagsRes
+ * type: object
+ * properties:
+ *   tags:
+ *     type: array
+ *     items:
+ *       properties:
+ *         id:
+ *           description: The ID of the tag.
+ *           type: string
+ *         usage_count:
+ *           description: The number of products that use this tag.
+ *           type: string
+ *         value:
+ *           description: The value of the tag.
+ *           type: string
+ */
 export type AdminProductsListTagsRes = {
-  tags: ProductTag[]
+  tags: Array<
+    Pick<ProductTag, "id" | "value"> & {
+      usage_count: number
+    }
+  >
 }
 
+/**
+ * @schema AdminProductsRes
+ * type: object
+ * properties:
+ *   product:
+ *     $ref: "#/components/schemas/Product"
+ */
 export type AdminProductsRes = {
   product: Product
 }

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

@@ -185,21 +185,7 @@ import { FilterableProductProps } from "../../../../types/product"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminProductsListRes"
- *           properties:
- *             products:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/Product"
- *             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/products/list-tag-usage-count.ts

@@ -33,21 +33,7 @@ import { ProductService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminProductsListTagsRes"
- *           properties:
- *             tags:
- *               type: array
- *               items:
- *                 properties:
- *                   id:
- *                     description: The ID of the tag.
- *                     type: string
- *                   usage_count:
- *                     description: The number of products that use this tag.
- *                     type: string
- *                   value:
- *                     description: The value of the tag.
- *                     type: string
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/products/list-types.ts

@@ -34,12 +34,7 @@ import { ProductService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminProductsListTypesRes"
- *           properties:
- *             types:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/ProductType"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/products/list-variants.ts

@@ -37,21 +37,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminProductsListVariantsRes"
- *           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":

packages/medusa/src/api/routes/admin/products/set-metadata.ts

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

packages/medusa/src/api/routes/admin/products/update-option.ts

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

packages/medusa/src/api/routes/admin/products/update-product.ts

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

packages/medusa/src/api/routes/admin/products/update-variant.ts

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

packages/medusa/src/api/routes/admin/publishable-api-keys/add-channels-batch.ts

@@ -60,9 +60,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key"
  *     content:
  *       application/json:
  *         schema:
- *           properties:
+ *           $ref: "#/components/schemas/AdminPublishableApiKeysRes"
- *             publishable_api_key:
- *               $ref: "#/components/schemas/PublishableApiKey"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/publishable-api-keys/create-publishable-api-key.ts

@@ -48,10 +48,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminPublishableApiKeysRes"
- *           properties:
- *             publishable_api_key:
- *               $ref: "#/components/schemas/PublishableApiKey"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/publishable-api-keys/delete-channels-batch.ts

@@ -60,9 +60,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key"
  *     content:
  *       application/json:
  *         schema:
- *           properties:
+ *           $ref: "#/components/schemas/AdminPublishableApiKeysRes"
- *             publishable_api_key:
- *               $ref: "#/components/schemas/PublishableApiKey"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/publishable-api-keys/delete-publishable-api-key.ts

@@ -37,19 +37,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminPublishableApiKeyDeleteRes"
- *           properties:
- *             id:
- *               type: string
- *               description: The ID of the deleted PublishableApiKey.
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               format: publishable_api_key
- *             deleted:
- *               type: boolean
- *               description: Whether the PublishableApiKeys was deleted.
- *               default: true
  *   "400":
  *     $ref: "#/components/responses/400_error"
  */

packages/medusa/src/api/routes/admin/publishable-api-keys/get-publishable-api-key.ts

@@ -37,10 +37,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminPublishableApiKeysRes"
- *           properties:
- *             publishable_api_key:
- *               $ref: "#/components/schemas/PublishableApiKey"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/publishable-api-keys/index.ts

@@ -7,7 +7,7 @@ import middlewares, {
   transformQuery,
 } from "../../../middlewares"
 import { GetPublishableApiKeysParams } from "./list-publishable-api-keys"
-import { PublishableApiKey } from "../../../../models"
+import { PublishableApiKey, SalesChannel } from "../../../../models"
 import { DeleteResponse, PaginatedResponse } from "../../../../types/common"
 import { AdminPostPublishableApiKeysReq } from "./create-publishable-api-key"
 import { AdminPostPublishableApiKeysPublishableApiKeyReq } from "./update-publishable-api-key"
@@ -80,14 +80,70 @@ export default (app) => {
   )
 }
 
+/**
+ * @schema AdminPublishableApiKeysRes
+ * type: object
+ * properties:
+ *   publishable_api_key:
+ *     $ref: "#/components/schemas/PublishableApiKey"
+ */
 export type AdminPublishableApiKeysRes = {
   publishable_api_key: PublishableApiKey
 }
+
+/**
+ * @schema AdminPublishableApiKeysListRes
+ * type: object
+ * properties:
+ *   publishable_api_keys:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/PublishableApiKey"
+ *   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 AdminPublishableApiKeysListRes = PaginatedResponse & {
   publishable_api_keys: PublishableApiKey[]
 }
+
+/**
+ * @schema AdminPublishableApiKeyDeleteRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted PublishableApiKey.
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: publishable_api_key
+ *   deleted:
+ *     type: boolean
+ *     description: Whether the PublishableApiKeys was deleted.
+ *     default: true
+ */
 export type AdminPublishableApiKeyDeleteRes = DeleteResponse
 
+/**
+ * @schema AdminPublishableApiKeysListSalesChannelsRes
+ * type: object
+ * properties:
+ *   sales_channels:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/SalesChannel"
+ */
+export type AdminPublishableApiKeysListSalesChannelsRes = {
+  sales_channels: SalesChannel[]
+}
+
 export * from "./add-channels-batch"
 export * from "./delete-channels-batch"
 export * from "./list-publishable-api-keys"

packages/medusa/src/api/routes/admin/publishable-api-keys/list-publishable-api-key-sales-channels.ts

@@ -40,11 +40,7 @@ import { extendedFindParamsMixin } from "../../../../types/common"
  *     content:
  *       application/json:
  *         schema:
- *          properties:
+ *           $ref: "#/components/schemas/AdminPublishableApiKeysListSalesChannelsRes"
- *             sales_channels:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/SalesChannel"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/publishable-api-keys/list-publishable-api-keys.ts

@@ -43,11 +43,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminPublishableApiKeysListRes"
- *           properties:
- *             publishable_api_keys:
- *               type: array
- *               $ref: "#/components/schemas/PublishableApiKey"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/publishable-api-keys/revoke-publishable-api-key.ts

@@ -38,10 +38,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminPublishableApiKeysRes"
- *           properties:
- *             publishable_api_key:
- *               $ref: "#/components/schemas/PublishableApiKey"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/publishable-api-keys/update-publishable-api-key.ts

@@ -50,10 +50,7 @@ import PublishableApiKeyService from "../../../../services/publishable-api-key"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminPublishableApiKeysRes"
- *           properties:
- *             publishable_api_key:
- *               $ref: "#/components/schemas/PublishableApiKey"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/regions/add-country.ts

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

packages/medusa/src/api/routes/admin/regions/add-fulfillment-provider.ts

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

packages/medusa/src/api/routes/admin/regions/add-payment-provider.ts

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

packages/medusa/src/api/routes/admin/regions/create-region.ts

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

packages/medusa/src/api/routes/admin/regions/delete-region.ts

@@ -36,19 +36,7 @@ import RegionService from "../../../../services/region"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminRegionsDeleteRes"
- *           properties:
- *             id:
- *               type: string
- *               description: The ID of the deleted Region.
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               default: region
- *             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/regions/get-fulfillment-options.ts

@@ -37,22 +37,7 @@ import RegionService from "../../../../services/region"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminGetRegionsRegionFulfillmentOptionsRes"
- *           properties:
- *             fulfillment_options:
- *               type: array
- *               items:
- *                 properties:
- *                   provider_id:
- *                     type: string
- *                     description: ID of the fulfillment provider
- *                   options:
- *                     type: array
- *                     description: fulfillment provider options
- *                     example:
- *                       - id: "manual-fulfillment"
- *                       - id: "manual-fulfillment-return"
- *                         is_return: true
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/regions/get-region.ts

@@ -37,10 +37,7 @@ import RegionService from "../../../../services/region"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminRegionsRes"
- *           properties:
- *             region:
- *               $ref: "#/components/schemas/Region"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

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

@@ -85,14 +85,55 @@ export const defaultAdminRegionRelations = [
   "fulfillment_providers",
 ]
 
+/**
+ * @schema AdminRegionsRes
+ * type: object
+ * properties:
+ *   region:
+ *     $ref: "#/components/schemas/Region"
+ */
 export class AdminRegionsRes {
   region: Region
 }
 
+/**
+ * @schema AdminRegionsListRes
+ * type: object
+ * properties:
+ *   regions:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/Region"
+ *   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 AdminRegionsListRes = PaginatedResponse & {
   regions: Region[]
 }
 
+/**
+ * @schema AdminRegionsDeleteRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted Region.
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: region
+ *   deleted:
+ *     type: boolean
+ *     description: Whether or not the items were deleted.
+ *     default: true
+ */
 export type AdminRegionsDeleteRes = DeleteResponse
 
 export class FulfillmentOption {
@@ -100,6 +141,26 @@ export class FulfillmentOption {
   options: unknown[]
 }
 
+/**
+ * @schema AdminGetRegionsRegionFulfillmentOptionsRes
+ * type: object
+ * properties:
+ *   fulfillment_options:
+ *     type: array
+ *     items:
+ *       type: object
+ *       properties:
+ *         provider_id:
+ *           type: string
+ *           description: ID of the fulfillment provider
+ *         options:
+ *           type: array
+ *           description: fulfillment provider options
+ *           example:
+ *             - id: "manual-fulfillment"
+ *             - id: "manual-fulfillment-return"
+ *               is_return: true
+ */
 export class AdminGetRegionsRegionFulfillmentOptionsRes {
   fulfillment_options: FulfillmentOption[]
 }

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

@@ -74,21 +74,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminRegionsListRes"
- *           properties:
- *             regions:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/Region"
- *             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/regions/remove-country.ts

@@ -47,10 +47,7 @@ import RegionService from "../../../../services/region"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminRegionsRes"
- *           properties:
- *             region:
- *               $ref: "#/components/schemas/Region"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/regions/remove-fulfillment-provider.ts

@@ -39,10 +39,7 @@ import RegionService from "../../../../services/region"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminRegionsRes"
- *           properties:
- *             region:
- *               $ref: "#/components/schemas/Region"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/regions/remove-payment-provider.ts

@@ -39,10 +39,7 @@ import RegionService from "../../../../services/region"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminRegionsRes"
- *           properties:
- *             region:
- *               $ref: "#/components/schemas/Region"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/regions/update-region.ts

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

packages/medusa/src/api/routes/admin/return-reasons/create-reason.ts

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

packages/medusa/src/api/routes/admin/return-reasons/delete-reason.ts

@@ -36,19 +36,7 @@ import { ReturnReasonService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminReturnReasonsDeleteRes"
- *           properties:
- *             id:
- *               type: string
- *               description: The ID of the deleted return reason
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               default: return_reason
- *             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/return-reasons/get-reason.ts

@@ -40,10 +40,7 @@ import { ReturnReasonService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminReturnReasonsRes"
- *           properties:
- *             return_reason:
- *               $ref: "#/components/schemas/ReturnReason"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/return-reasons/index.ts

@@ -52,14 +52,46 @@ export const defaultAdminReturnReasonsRelations: (keyof ReturnReason)[] = [
   "return_reason_children",
 ]
 
+/**
+ * @schema AdminReturnReasonsRes
+ * type: object
+ * properties:
+ *   return_reason:
+ *     $ref: "#/components/schemas/ReturnReason"
+ */
 export type AdminReturnReasonsRes = {
   return_reason: ReturnReason
 }
 
+/**
+ * @schema AdminReturnReasonsListRes
+ * type: object
+ * properties:
+ *   return_reasons:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/ReturnReason"
+ */
 export type AdminReturnReasonsListRes = {
   return_reasons: ReturnReason[]
 }
 
+/**
+ * @schema AdminReturnReasonsDeleteRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted return reason
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: return_reason
+ *   deleted:
+ *     type: boolean
+ *     description: Whether or not the items were deleted.
+ *     default: true
+ */
 export type AdminReturnReasonsDeleteRes = DeleteResponse
 
 export * from "./create-reason"

packages/medusa/src/api/routes/admin/return-reasons/list-reasons.ts

@@ -39,12 +39,7 @@ import { Selector } from "../../../../types/common"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminReturnReasonsListRes"
- *           properties:
- *             return_reasons:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/ReturnReason"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/return-reasons/update-reason.ts

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

packages/medusa/src/api/routes/admin/returns/cancel-return.ts

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

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

@@ -27,14 +27,46 @@ export default (app) => {
   return app
 }
 
+/**
+ * @schema AdminReturnsCancelRes
+ * type: object
+ * properties:
+ *   order:
+ *     $ref: "#/components/schemas/Order"
+ */
 export type AdminReturnsCancelRes = {
   order: Order
 }
 
+/**
+ * @schema AdminReturnsListRes
+ * type: object
+ * properties:
+ *   returns:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/Return"
+ *   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 AdminReturnsListRes = PaginatedResponse & {
   returns: Return[]
 }
 
+/**
+ * @schema AdminReturnsRes
+ * type: object
+ * properties:
+ *   return:
+ *     $ref: "#/components/schemas/Return"
+ */
 export type AdminReturnsRes = {
   return: Return
 }

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

@@ -41,21 +41,7 @@ import { Return } from "../../../../models"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminReturnsListRes"
- *           properties:
- *             returns:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/Return"
- *             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/returns/receive-return.ts

@@ -5,12 +5,7 @@ import {
   IsString,
   ValidateNested,
 } from "class-validator"
-import {
+import { OrderService, ReturnService, SwapService } from "../../../../services"
-  OrderService,
-  ProductVariantInventoryService,
-  ReturnService,
-  SwapService,
-} from "../../../../services"
 
 import { EntityManager } from "typeorm"
 import { Type } from "class-transformer"
@@ -72,10 +67,7 @@ import { isDefined } from "medusa-core-utils"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminReturnsRes"
- *           properties:
- *             return:
- *               $ref: "#/components/schemas/Return"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/sales-channels/add-product-batch.ts

@@ -60,10 +60,7 @@ import { Type } from "class-transformer"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminSalesChannelsRes"
- *           properties:
- *             sales_channel:
- *               $ref: "#/components/schemas/SalesChannel"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/sales-channels/associate-stock-location.ts

@@ -3,8 +3,8 @@ import { Request, Response } from "express"
 import { EntityManager } from "typeorm"
 
 import {
-  SalesChannelService,
   SalesChannelLocationService,
+  SalesChannelService,
 } from "../../../../services"
 
 /**
@@ -53,10 +53,7 @@ import {
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminSalesChannelsRes"
- *           properties:
- *             sales_channel:
- *               $ref: "#/components/schemas/SalesChannel"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/sales-channels/create-sales-channel.ts

@@ -50,10 +50,7 @@ import SalesChannelService from "../../../../services/sales-channel"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminSalesChannelsRes"
- *           properties:
- *             sales_channel:
- *               $ref: "#/components/schemas/SalesChannel"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/sales-channels/delete-products-batch.ts

@@ -60,10 +60,7 @@ import { Type } from "class-transformer"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminSalesChannelsRes"
- *           properties:
- *             sales_channel:
- *               $ref: "#/components/schemas/SalesChannel"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

packages/medusa/src/api/routes/admin/sales-channels/delete-sales-channel.ts

@@ -38,19 +38,7 @@ import { SalesChannelService } from "../../../../services/"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminSalesChannelsDeleteRes"
- *           properties:
- *             id:
- *               type: string
- *               description: The ID of the deleted sales channel
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               default: sales-channel
- *             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/sales-channels/get-sales-channel.ts

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

packages/medusa/src/api/routes/admin/sales-channels/index.ts

@@ -76,12 +76,71 @@ export default (app) => {
   return app
 }
 
+/**
+ * @schema AdminSalesChannelsRes
+ * type: object
+ * properties:
+ *   sales_channel:
+ *     $ref: "#/components/schemas/SalesChannel"
+ */
 export type AdminSalesChannelsRes = {
   sales_channel: SalesChannel
 }
 
+/**
+ * @schema AdminSalesChannelsDeleteRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted sales channel
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: sales-channel
+ *   deleted:
+ *     type: boolean
+ *     description: Whether or not the items were deleted.
+ *     default: true
+ */
 export type AdminSalesChannelsDeleteRes = DeleteResponse
 
+/**
+ * @schema AdminSalesChannelsDeleteLocationRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the removed stock location from a sales channel
+ *   object:
+ *     type: string
+ *     description: The type of the object that was removed.
+ *     default: stock-location
+ *   deleted:
+ *     type: boolean
+ *     description: Whether or not the items were deleted.
+ *     default: true
+ */
+export type AdminSalesChannelsDeleteLocationRes = DeleteResponse
+
+/**
+ * @schema AdminSalesChannelsListRes
+ * type: object
+ * properties:
+ *   sales_channels:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/SalesChannel"
+ *   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 AdminSalesChannelsListRes = PaginatedResponse & {
   sales_channels: SalesChannel[]
 }

packages/medusa/src/api/routes/admin/sales-channels/list-sales-channels.ts

@@ -117,21 +117,7 @@ import { Type } from "class-transformer"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminSalesChannelsListRes"
- *           properties:
- *             sales_channels:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/SalesChannel"
- *             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/sales-channels/remove-stock-location.ts

@@ -50,19 +50,7 @@ import { SalesChannelLocationService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/AdminSalesChannelsDeleteLocationRes"
- *           properties:
- *             id:
- *               type: string
- *               description: The ID of the removed stock location from a sales channel
- *             object:
- *               type: string
- *               description: The type of the object that was removed.
- *               default: stock-location
- *             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/sales-channels/update-sales-channel.ts

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