chore(oas): replace response with $ref class JSDoc (Store PRO-V) (#3044)

### Scope

Store routes directories PRO to V.

### What

Move inline OAS response schema declaration under their respective class declarations in order to expose them through  `#/components/schemas`. Replace inline OAS response schema with a `$ref` reference pointing to the newly declared schema.

### Why

Having response declared as its own "named" schema will allow OAS code generators to output typed entities/DTO that can be consumed without having to reference the route/operation.

### How

Declare a new @schema JSDoc for each "Res" class used to parse and validate request body. Move the current inline requestBody to the new @schema.

### Test

- Ran OAS validator.
- Ran docs build script.

Expect no visible changes to the documentation.

.changeset/spicy-windows-invent.md

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

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

@@ -211,7 +211,9 @@ export type AdminProductsDeleteRes = {
  *   products:
  *     type: array
  *     items:
- *       $ref: "#/components/schemas/Product"
+ *       oneOf:
+ *         - $ref: "#/components/schemas/Product"
+ *         - $ref: "#/components/schemas/PricedProduct"
  *   count:
  *     type: integer
  *     description: The total number of items available

packages/medusa/src/api/routes/store/product-categories/get-product-category.ts

@@ -3,7 +3,7 @@ import { Request, Response } from "express"
 import ProductCategoryService from "../../../../services/product-category"
 import { FindParams } from "../../../../types/common"
 import { transformTreeNodesWithConfig } from "../../../../utils/transformers/tree"
-import { defaultStoreProductCategoryRelations, defaultStoreScope } from "."
+import { defaultStoreScope } from "."
 
 /**
  * @oas [get] /product-categories/{id}
@@ -42,10 +42,7 @@ import { defaultStoreProductCategoryRelations, defaultStoreScope } from "."
  *    content:
  *      application/json:
  *        schema:
- *          type: object
+ *          $ref: "#/components/schemas/StoreGetProductCategoryRes"
- *          properties:
- *            productCategory:
- *              $ref: "#/components/schemas/ProductCategory"
  *  "400":
  *    $ref: "#/components/responses/400_error"
  *  "401":

packages/medusa/src/api/routes/store/product-categories/index.ts

@@ -3,6 +3,7 @@ import middlewares, { transformQuery } from "../../../middlewares"
 import getProductCategory, {
   StoreGetProductCategoryParams,
 } from "./get-product-category"
+import { ProductCategory } from "../../../../models"
 
 import listProductCategories, {
   StoreGetProductCategoriesParams,
@@ -66,5 +67,16 @@ export const allowedStoreProductCategoryFields = [
   "updated_at",
 ]
 
+/**
+ * @schema StoreGetProductCategoryRes
+ * type: object
+ * properties:
+ *   product_category:
+ *     $ref: "#/components/schemas/ProductCategory"
+ */
+export type StoreGetProductCategoryRes = {
+  product_category: ProductCategory
+}
+
 export * from "./get-product-category"
 export * from "./list-product-categories"

packages/medusa/src/api/routes/store/product-types/index.ts

@@ -39,12 +39,26 @@ export const defaultStoreProductTypeFields = [
 ]
 export const defaultStoreProductTypeRelations = []
 
+/**
+ * @schema StoreProductTypesListRes
+ * 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 StoreProductTypesListRes = PaginatedResponse & {
   product_types: ProductType[]
 }
 
-export type StoreProductTypesRes = {
-  product_type: ProductType
-}
-
 export * from "./list-product-types"

packages/medusa/src/api/routes/store/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/StoreProductTypesListRes"
- *          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/store/products/get-product.ts

@@ -49,19 +49,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/StoreProductsRes"
- *           properties:
- *             product:
- *               allOf:
- *                 - $ref: "#/components/schemas/Product"
- *                 - type: object
- *                   properties:
- *                     variants:
- *                       type: array
- *                       items:
- *                         allOf:
- *                           - $ref: "#/components/schemas/ProductVariant"
- *                           - $ref: "#/components/schemas/ProductVariantPricesFields"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":

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

@@ -54,15 +54,48 @@ export const defaultStoreProductsRelations = [
 export * from "./list-products"
 export * from "./search"
 
+/**
+ * @schema StoreProductsRes
+ * type: object
+ * properties:
+ *   product:
+ *     $ref: "#/components/schemas/PricedProduct"
+ */
 export type StoreProductsRes = {
   product: Product
 }
 
+/**
+ * @schema StorePostSearchRes
+ * type: object
+ * properties:
+ *   hits:
+ *     type: array
+ *     description: Array of results. The format of the items depends on the search engine installed on the server.
+ */
 export type StorePostSearchRes = {
   hits: unknown[]
   [k: string]: unknown
 }
 
+/**
+ * @schema StoreProductsListRes
+ * type: object
+ * properties:
+ *   products:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/PricedProduct"
+ *   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 StoreProductsListRes = PaginatedResponse & {
   products: Product[]
 }

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

@@ -151,30 +151,7 @@ import PublishableAPIKeysFeatureFlag from "../../../../loaders/feature-flags/pub
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/StoreProductsListRes"
- *           properties:
- *             products:
- *               type: array
- *               items:
- *                 allOf:
- *                   - $ref: "#/components/schemas/Product"
- *                   - type: object
- *                     properties:
- *                       variants:
- *                         type: array
- *                         items:
- *                           allOf:
- *                             - $ref: "#/components/schemas/ProductVariant"
- *                             - $ref: "#/components/schemas/ProductVariantPricesFields"
- *             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"
  *   "404":

packages/medusa/src/api/routes/store/products/search.ts

@@ -39,11 +39,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/StorePostSearchRes"
- *           properties:
- *             hits:
- *               type: array
- *               description: Array of results. The format of the items depends on the search engine installed on the server.
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":

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

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

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

@@ -13,10 +13,26 @@ export default (app) => {
   return app
 }
 
+/**
+ * @schema StoreRegionsListRes
+ * type: object
+ * properties:
+ *   regions:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/Region"
+ */
 export type StoreRegionsListRes = {
   regions: Region[]
 }
 
+/**
+ * @schema StoreRegionsRes
+ * type: object
+ * properties:
+ *   region:
+ *     $ref: "#/components/schemas/Region"
+ */
 export type StoreRegionsRes = {
   region: Region
 }

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

@@ -80,12 +80,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/StoreRegionsListRes"
- *           properties:
- *             regions:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/Region"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":

packages/medusa/src/api/routes/store/return-reasons/get-reason.ts

@@ -33,10 +33,7 @@ import ReturnReasonService from "../../../../services/return-reason"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/StoreReturnReasonsRes"
- *           properties:
- *             return_reason:
- *               $ref: "#/components/schemas/ReturnReason"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":

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

@@ -36,10 +36,26 @@ export const defaultStoreReturnReasonRelations: (keyof ReturnReason)[] = [
   "return_reason_children",
 ]
 
+/**
+ * @schema StoreReturnReasonsListRes
+ * type: object
+ * properties:
+ *   return_reasons:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/ReturnReason"
+ */
 export type StoreReturnReasonsListRes = {
   return_reasons: ReturnReason[]
 }
 
+/**
+ * @schema StoreReturnReasonsRes
+ * type: object
+ * properties:
+ *   return_reason:
+ *     $ref: "#/components/schemas/ReturnReason"
+ */
 export type StoreReturnReasonsRes = {
   return_reason: ReturnReason
 }

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

@@ -31,12 +31,7 @@ import ReturnReasonService from "../../../../services/return-reason"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/StoreReturnReasonsListRes"
- *           properties:
- *             return_reasons:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/ReturnReason"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":

packages/medusa/src/api/routes/store/returns/create-return.ts

@@ -66,10 +66,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/StoreReturnsRes"
- *           properties:
- *             return:
- *               $ref: "#/components/schemas/Return"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":

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

@@ -12,6 +12,13 @@ export default (app) => {
   return app
 }
 
+/**
+ * @schema StoreReturnsRes
+ * type: object
+ * properties:
+ *   return:
+ *     $ref: "#/components/schemas/Return"
+ */
 export type StoreReturnsRes = {
   return: Return
 }

packages/medusa/src/api/routes/store/shipping-options/index.ts

@@ -16,6 +16,15 @@ export default (app) => {
   return app
 }
 
+/**
+ * @schema StoreShippingOptionsListRes
+ * type: object
+ * properties:
+ *   shipping_options:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/ShippingOption"
+ */
 export type StoreShippingOptionsListRes = {
   shipping_options: ShippingOption[]
 }

packages/medusa/src/api/routes/store/shipping-options/list-options.ts

@@ -34,12 +34,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/StoreShippingOptionsListRes"
- *           properties:
- *             shipping_options:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/ShippingOption"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":

packages/medusa/src/api/routes/store/shipping-options/list-shipping-options.ts

@@ -30,12 +30,7 @@ import ShippingProfileService from "../../../../services/shipping-profile"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/StoreShippingOptionsListRes"
- *           properties:
- *             shipping_options:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/ShippingOption"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":

packages/medusa/src/api/routes/store/swaps/create-swap.ts

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

packages/medusa/src/api/routes/store/swaps/get-swap-by-cart.ts

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

packages/medusa/src/api/routes/store/swaps/index.ts

@@ -45,6 +45,13 @@ export const defaultStoreSwapFields: FindConfig<Swap>["select"] = [
   "idempotency_key",
 ]
 
+/**
+ * @schema StoreSwapsRes
+ * type: object
+ * properties:
+ *   swap:
+ *     $ref: "#/components/schemas/Swap"
+ */
 export type StoreSwapsRes = {
   swap: Swap
 }

packages/medusa/src/api/routes/store/variants/get-variant.ts

@@ -41,12 +41,7 @@ import { validator } from "../../../../utils/validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/StoreVariantsRes"
- *           properties:
- *             variant:
- *               allOf:
- *                 - $ref: "#/components/schemas/ProductVariant"
- *                 - $ref: "#/components/schemas/ProductVariantPricesFields"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":

packages/medusa/src/api/routes/store/variants/index.ts

@@ -1,4 +1,3 @@
-import { PaginatedResponse } from "./../../../../types/common"
 import { ProductVariant } from "../../../../"
 import { Router } from "express"
 import middlewares from "../../../middlewares"
@@ -16,11 +15,27 @@ export default (app) => {
 
 export const defaultStoreVariantRelations = ["prices", "options"]
 
+/**
+ * @schema StoreVariantsRes
+ * type: object
+ * properties:
+ *   variant:
+ *     $ref: "#/components/schemas/PricedVariant"
+ */
 export type StoreVariantsRes = {
   variant: ProductVariant
 }
 
-export type StoreVariantsListRes = PaginatedResponse & {
+/**
+ * @schema StoreVariantsListRes
+ * type: object
+ * properties:
+ *   variants:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/PricedVariant"
+ */
+export type StoreVariantsListRes = {
   variants: ProductVariant[]
 }
 

packages/medusa/src/api/routes/store/variants/list-variants.ts

@@ -73,14 +73,7 @@ import { IsType } from "../../../../utils/validators/is-type"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
+ *           $ref: "#/components/schemas/StoreVariantsListRes"
- *           properties:
- *             variants:
- *               type: array
- *               items:
- *                 allOf:
- *                   - $ref: "#/components/schemas/ProductVariant"
- *                   - $ref: "#/components/schemas/ProductVariantPricesFields"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "404":

packages/medusa/src/models/product-variant.ts

@@ -216,44 +216,3 @@ export class ProductVariant extends SoftDeletableEntity {
  *     description: An optional key-value map with additional details
  *     example: {car: "white"}
  */
-
-/**
- * @schema ProductVariantPricesFields
- * title: "Product Variant Prices Fields"
- * description: "Product Variants Prices Fields that are only available in some requests."
- * type: object
- * properties:
- *   original_price:
- *     type: number
- *     description: The original price of the variant without any discounted prices applied.
- *   calculated_price:
- *     type: number
- *     description: The calculated price of the variant. Can be a discounted price.
- *   original_price_incl_tax:
- *     type: number
- *     description: The original price of the variant including taxes.
- *   calculated_price_incl_tax:
- *     type: number
- *     description: The calculated price of the variant including taxes.
- *   original_tax:
- *     type: number
- *     description: The taxes applied on the original price.
- *   calculated_tax:
- *     type: number
- *     description: The taxes applied on the calculated price.
- *   tax_rates:
- *     type: array
- *     description: An array of applied tax rates
- *     items:
- *       type: object
- *       properties:
- *         rate:
- *           type: number
- *           description: The tax rate value
- *         name:
- *           type: string
- *           description: The name of the tax rate
- *         code:
- *           type: string
- *           description: The code of the tax rate
- */

packages/medusa/src/types/pricing.ts

@@ -34,8 +34,63 @@ export type ShippingOptionPricing = {
 export type PricedShippingOption = Partial<ShippingOption> &
   ShippingOptionPricing
 
+/**
+ * @schema PricedVariant
+ * title: "Priced Product Variant"
+ * type: object
+ * allOf:
+ *   - $ref: "#/components/schemas/ProductVariant"
+ *   - type: object
+ *     properties:
+ *       original_price:
+ *         type: number
+ *         description: The original price of the variant without any discounted prices applied.
+ *       calculated_price:
+ *         type: number
+ *         description: The calculated price of the variant. Can be a discounted price.
+ *       original_price_incl_tax:
+ *         type: number
+ *         description: The original price of the variant including taxes.
+ *       calculated_price_incl_tax:
+ *         type: number
+ *         description: The calculated price of the variant including taxes.
+ *       original_tax:
+ *         type: number
+ *         description: The taxes applied on the original price.
+ *       calculated_tax:
+ *         type: number
+ *         description: The taxes applied on the calculated price.
+ *       tax_rates:
+ *         type: array
+ *         description: An array of applied tax rates
+ *         items:
+ *           type: object
+ *           properties:
+ *             rate:
+ *               type: number
+ *               description: The tax rate value
+ *             name:
+ *               type: string
+ *               description: The name of the tax rate
+ *             code:
+ *               type: string
+ *               description: The code of the tax rate
+ */
 export type PricedVariant = Partial<ProductVariant> & ProductVariantPricing
 
+/**
+ * @schema PricedProduct
+ * title: "Priced Product"
+ * type: object
+ * allOf:
+ *   - $ref: "#/components/schemas/Product"
+ *   - type: object
+ *     properties:
+ *       variants:
+ *         type: array
+ *         items:
+ *           $ref: "#/components/schemas/PricedVariant"
+ */
 export type PricedProduct = Omit<Partial<Product>, "variants"> & {
   variants: PricedVariant[]
 }