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>
2023-01-16 11:00:05 -05:00
parent 8c08d00319
commit a0c4cfe0f7
65 changed files with 476 additions and 414 deletions
--- a/.changeset/quiet-peas-compete.md
+++ b/.changeset/quiet-peas-compete.md
@@ -0,0 +1,5 @@
+---
+"@medusajs/medusa": patch
+---
+
+chore(oas): replace response with $ref class JSDoc (Admin PR0-SAL)
--- a/.changeset/silent-pants-doubt.md
+++ b/.changeset/silent-pants-doubt.md
@@ -0,0 +1,5 @@
+---
+"@medusajs/medusa": patch
+---
+
+chore(oas): replace response with $ref class JSDoc (Admin PR0-SAL)
--- a/packages/medusa/src/api/routes/admin/product-tags/index.ts
+++ b/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"
--- a/packages/medusa/src/api/routes/admin/product-tags/list-product-tags.ts
+++ b/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
- *          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
+ *          $ref: "#/components/schemas/AdminProductTagsListRes"
 *  "400":
 *    $ref: "#/components/responses/400_error"
 *  "401":
--- a/packages/medusa/src/api/routes/admin/product-types/index.ts
+++ b/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"
--- a/packages/medusa/src/api/routes/admin/product-types/list-product-types.ts
+++ b/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
- *          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
+ *          $ref: "#/components/schemas/AdminProductTypesListRes"
 *  "400":
 *    $ref: "#/components/responses/400_error"
 *  "401":
--- a/packages/medusa/src/api/routes/admin/products/add-option.ts
+++ b/packages/medusa/src/api/routes/admin/products/add-option.ts
@@ -51,10 +51,7 @@ import { EntityManager } from "typeorm"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             product:
- *               $ref: "#/components/schemas/Product"
+ *           $ref: "#/components/schemas/AdminProductsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/products/create-product.ts
+++ b/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
- *           properties:
- *             product:
- *               $ref: "#/components/schemas/Product"
+ *           $ref: "#/components/schemas/AdminProductsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/products/create-variant.ts
+++ b/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
- *           properties:
- *             product:
- *               $ref: "#/components/schemas/Product"
+ *           $ref: "#/components/schemas/AdminProductsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/products/delete-option.ts
+++ b/packages/medusa/src/api/routes/admin/products/delete-option.ts
@@ -39,21 +39,7 @@ import { ProductService } from "../../../../services"
 *     content:
 *       application/json:
 *         schema:
- *           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"
+ *           $ref: "#/components/schemas/AdminProductsDeleteOptionRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/products/delete-product.ts
+++ b/packages/medusa/src/api/routes/admin/products/delete-product.ts
@@ -36,19 +36,7 @@ import { ProductService } from "../../../../services"
 *     content:
 *       application/json:
 *         schema:
- *           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
+ *           $ref: "#/components/schemas/AdminProductsDeleteRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/products/delete-variant.ts
+++ b/packages/medusa/src/api/routes/admin/products/delete-variant.ts
@@ -43,21 +43,7 @@ import { EntityManager } from "typeorm"
 *     content:
 *       application/json:
 *         schema:
- *           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: variant
- *             deleted:
- *               type: boolean
- *               description: Whether or not the items were deleted.
- *               default: true
- *             product:
- *               $ref: "#/components/schemas/Product"
+ *           $ref: "#/components/schemas/AdminProductsDeleteVariantRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/products/get-product.ts
+++ b/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
- *           properties:
- *             product:
- *               $ref: "#/components/schemas/Product"
+ *           $ref: "#/components/schemas/AdminProductsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/products/index.ts
+++ b/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
 }
--- a/packages/medusa/src/api/routes/admin/products/list-products.ts
+++ b/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
- *           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
+ *           $ref: "#/components/schemas/AdminProductsListRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/products/list-tag-usage-count.ts
+++ b/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
- *           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
+ *           $ref: "#/components/schemas/AdminProductsListTagsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/products/list-types.ts
+++ b/packages/medusa/src/api/routes/admin/products/list-types.ts
@@ -34,12 +34,7 @@ import { ProductService } from "../../../../services"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             types:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/ProductType"
+ *           $ref: "#/components/schemas/AdminProductsListTypesRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/products/list-variants.ts
+++ b/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
- *           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/AdminProductsListVariantsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/products/set-metadata.ts
+++ b/packages/medusa/src/api/routes/admin/products/set-metadata.ts
@@ -52,10 +52,7 @@ import { EntityManager } from "typeorm"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             product:
- *               $ref: "#/components/schemas/Product"
+ *           $ref: "#/components/schemas/AdminProductsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/products/update-option.ts
+++ b/packages/medusa/src/api/routes/admin/products/update-option.ts
@@ -52,10 +52,7 @@ import { EntityManager } from "typeorm"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             product:
- *               $ref: "#/components/schemas/Product"
+ *           $ref: "#/components/schemas/AdminProductsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/products/update-product.ts
+++ b/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
- *           properties:
- *             product:
- *               $ref: "#/components/schemas/Product"
+ *           $ref: "#/components/schemas/AdminProductsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/products/update-variant.ts
+++ b/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
- *           properties:
- *             product:
- *               $ref: "#/components/schemas/Product"
+ *           $ref: "#/components/schemas/AdminProductsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/publishable-api-keys/add-channels-batch.ts
+++ b/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:
- *             publishable_api_key:
- *               $ref: "#/components/schemas/PublishableApiKey"
+ *           $ref: "#/components/schemas/AdminPublishableApiKeysRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/publishable-api-keys/create-publishable-api-key.ts
+++ b/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
- *           properties:
- *             publishable_api_key:
- *               $ref: "#/components/schemas/PublishableApiKey"
+ *           $ref: "#/components/schemas/AdminPublishableApiKeysRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/publishable-api-keys/delete-channels-batch.ts
+++ b/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:
- *             publishable_api_key:
- *               $ref: "#/components/schemas/PublishableApiKey"
+ *           $ref: "#/components/schemas/AdminPublishableApiKeysRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/publishable-api-keys/delete-publishable-api-key.ts
+++ b/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
- *           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
+ *           $ref: "#/components/schemas/AdminPublishableApiKeyDeleteRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 */
--- a/packages/medusa/src/api/routes/admin/publishable-api-keys/get-publishable-api-key.ts
+++ b/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
- *           properties:
- *             publishable_api_key:
- *               $ref: "#/components/schemas/PublishableApiKey"
+ *           $ref: "#/components/schemas/AdminPublishableApiKeysRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/publishable-api-keys/index.ts
+++ b/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"
--- a/packages/medusa/src/api/routes/admin/publishable-api-keys/list-publishable-api-key-sales-channels.ts
+++ b/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:
- *             sales_channels:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/SalesChannel"
+ *           $ref: "#/components/schemas/AdminPublishableApiKeysListSalesChannelsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/publishable-api-keys/list-publishable-api-keys.ts
+++ b/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
- *           properties:
- *             publishable_api_keys:
- *               type: array
- *               $ref: "#/components/schemas/PublishableApiKey"
+ *           $ref: "#/components/schemas/AdminPublishableApiKeysListRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/publishable-api-keys/revoke-publishable-api-key.ts
+++ b/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
- *           properties:
- *             publishable_api_key:
- *               $ref: "#/components/schemas/PublishableApiKey"
+ *           $ref: "#/components/schemas/AdminPublishableApiKeysRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/publishable-api-keys/update-publishable-api-key.ts
+++ b/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
- *           properties:
- *             publishable_api_key:
- *               $ref: "#/components/schemas/PublishableApiKey"
+ *           $ref: "#/components/schemas/AdminPublishableApiKeysRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/regions/add-country.ts
+++ b/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
- *           properties:
- *             region:
- *               $ref: "#/components/schemas/Region"
+ *           $ref: "#/components/schemas/AdminRegionsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/regions/add-fulfillment-provider.ts
+++ b/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
- *           properties:
- *             region:
- *               $ref: "#/components/schemas/Region"
+ *           $ref: "#/components/schemas/AdminRegionsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/regions/add-payment-provider.ts
+++ b/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
- *           properties:
- *             region:
- *               $ref: "#/components/schemas/Region"
+ *           $ref: "#/components/schemas/AdminRegionsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/regions/create-region.ts
+++ b/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
- *           properties:
- *             region:
- *               $ref: "#/components/schemas/Region"
+ *           $ref: "#/components/schemas/AdminRegionsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/regions/delete-region.ts
+++ b/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
- *           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
+ *           $ref: "#/components/schemas/AdminRegionsDeleteRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/regions/get-fulfillment-options.ts
+++ b/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
- *           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
+ *           $ref: "#/components/schemas/AdminGetRegionsRegionFulfillmentOptionsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/regions/get-region.ts
+++ b/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
- *           properties:
- *             region:
- *               $ref: "#/components/schemas/Region"
+ *           $ref: "#/components/schemas/AdminRegionsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/regions/index.ts
+++ b/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[]
 }
--- a/packages/medusa/src/api/routes/admin/regions/list-regions.ts
+++ b/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
- *           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
+ *           $ref: "#/components/schemas/AdminRegionsListRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/regions/remove-country.ts
+++ b/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
- *           properties:
- *             region:
- *               $ref: "#/components/schemas/Region"
+ *           $ref: "#/components/schemas/AdminRegionsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/regions/remove-fulfillment-provider.ts
+++ b/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
- *           properties:
- *             region:
- *               $ref: "#/components/schemas/Region"
+ *           $ref: "#/components/schemas/AdminRegionsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/regions/remove-payment-provider.ts
+++ b/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
- *           properties:
- *             region:
- *               $ref: "#/components/schemas/Region"
+ *           $ref: "#/components/schemas/AdminRegionsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/regions/update-region.ts
+++ b/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
- *           properties:
- *             region:
- *               $ref: "#/components/schemas/Region"
+ *           $ref: "#/components/schemas/AdminRegionsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/return-reasons/create-reason.ts
+++ b/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
- *           properties:
- *             return_reason:
- *               $ref: "#/components/schemas/ReturnReason"
+ *           $ref: "#/components/schemas/AdminReturnReasonsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/return-reasons/delete-reason.ts
+++ b/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
- *           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
+ *           $ref: "#/components/schemas/AdminReturnReasonsDeleteRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/return-reasons/get-reason.ts
+++ b/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
- *           properties:
- *             return_reason:
- *               $ref: "#/components/schemas/ReturnReason"
+ *           $ref: "#/components/schemas/AdminReturnReasonsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/return-reasons/index.ts
+++ b/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"
--- a/packages/medusa/src/api/routes/admin/return-reasons/list-reasons.ts
+++ b/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
- *           properties:
- *             return_reasons:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/ReturnReason"
+ *           $ref: "#/components/schemas/AdminReturnReasonsListRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/return-reasons/update-reason.ts
+++ b/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
- *           properties:
- *             return_reason:
- *               $ref: "#/components/schemas/ReturnReason"
+ *           $ref: "#/components/schemas/AdminReturnReasonsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/returns/cancel-return.ts
+++ b/packages/medusa/src/api/routes/admin/returns/cancel-return.ts
@@ -39,10 +39,7 @@ import { EntityManager } from "typeorm"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             order:
- *               $ref: "#/components/schemas/Order"
+ *           $ref: "#/components/schemas/AdminReturnsCancelRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/returns/index.ts
+++ b/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
 }
--- a/packages/medusa/src/api/routes/admin/returns/list-returns.ts
+++ b/packages/medusa/src/api/routes/admin/returns/list-returns.ts
@@ -41,21 +41,7 @@ import { Return } from "../../../../models"
 *     content:
 *       application/json:
 *         schema:
- *           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
+ *           $ref: "#/components/schemas/AdminReturnsListRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/returns/receive-return.ts
+++ b/packages/medusa/src/api/routes/admin/returns/receive-return.ts
@@ -5,12 +5,7 @@ import {
  IsString,
  ValidateNested,
 } from "class-validator"
-import {
-  OrderService,
-  ProductVariantInventoryService,
-  ReturnService,
-  SwapService,
-} from "../../../../services"
+import { OrderService, 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
- *           properties:
- *             return:
- *               $ref: "#/components/schemas/Return"
+ *           $ref: "#/components/schemas/AdminReturnsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/sales-channels/add-product-batch.ts
+++ b/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
- *           properties:
- *             sales_channel:
- *               $ref: "#/components/schemas/SalesChannel"
+ *           $ref: "#/components/schemas/AdminSalesChannelsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/sales-channels/associate-stock-location.ts
+++ b/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
- *           properties:
- *             sales_channel:
- *               $ref: "#/components/schemas/SalesChannel"
+ *           $ref: "#/components/schemas/AdminSalesChannelsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/sales-channels/create-sales-channel.ts
+++ b/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
- *           properties:
- *             sales_channel:
- *               $ref: "#/components/schemas/SalesChannel"
+ *           $ref: "#/components/schemas/AdminSalesChannelsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/sales-channels/delete-products-batch.ts
+++ b/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
- *           properties:
- *             sales_channel:
- *               $ref: "#/components/schemas/SalesChannel"
+ *           $ref: "#/components/schemas/AdminSalesChannelsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/sales-channels/delete-sales-channel.ts
+++ b/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
- *           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
+ *           $ref: "#/components/schemas/AdminSalesChannelsDeleteRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/sales-channels/get-sales-channel.ts
+++ b/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
- *           properties:
- *             sales_channel:
- *               $ref: "#/components/schemas/SalesChannel"
+ *           $ref: "#/components/schemas/AdminSalesChannelsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/sales-channels/index.ts
+++ b/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[]
 }
--- a/packages/medusa/src/api/routes/admin/sales-channels/list-sales-channels.ts
+++ b/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
- *           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
+ *           $ref: "#/components/schemas/AdminSalesChannelsListRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/sales-channels/remove-stock-location.ts
+++ b/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
- *           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
+ *           $ref: "#/components/schemas/AdminSalesChannelsDeleteLocationRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/admin/sales-channels/update-sales-channel.ts
+++ b/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
- *           properties:
- *             sales_channel:
- *               $ref: "#/components/schemas/SalesChannel"
+ *           $ref: "#/components/schemas/AdminSalesChannelsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":