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.
2023-01-17 09:22:10 -05:00
parent 0175388835
commit cb1ec0076b
29 changed files with 215 additions and 166 deletions
--- a/.changeset/spicy-windows-invent.md
+++ b/.changeset/spicy-windows-invent.md
@@ -0,0 +1,5 @@
+---
+"@medusajs/medusa": patch
+---
+
+chore(oas): replace response with $ref class JSDoc (Store PRO-V)
--- a/packages/medusa/src/api/routes/admin/products/index.ts
+++ b/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
--- a/packages/medusa/src/api/routes/store/product-categories/get-product-category.ts
+++ b/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
- *          properties:
- *            productCategory:
- *              $ref: "#/components/schemas/ProductCategory"
+ *          $ref: "#/components/schemas/StoreGetProductCategoryRes"
 *  "400":
 *    $ref: "#/components/responses/400_error"
 *  "401":
--- a/packages/medusa/src/api/routes/store/product-categories/index.ts
+++ b/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"
--- a/packages/medusa/src/api/routes/store/product-types/index.ts
+++ b/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"
--- a/packages/medusa/src/api/routes/store/product-types/list-product-types.ts
+++ b/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
- *          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/StoreProductTypesListRes"
 *  "400":
 *    $ref: "#/components/responses/400_error"
 *  "401":
--- a/packages/medusa/src/api/routes/store/products/get-product.ts
+++ b/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
- *           properties:
- *             product:
- *               allOf:
- *                 - $ref: "#/components/schemas/Product"
- *                 - type: object
- *                   properties:
- *                     variants:
- *                       type: array
- *                       items:
- *                         allOf:
- *                           - $ref: "#/components/schemas/ProductVariant"
- *                           - $ref: "#/components/schemas/ProductVariantPricesFields"
+ *           $ref: "#/components/schemas/StoreProductsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/products/index.ts
+++ b/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[]
 }
--- a/packages/medusa/src/api/routes/store/products/list-products.ts
+++ b/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
- *           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
+ *           $ref: "#/components/schemas/StoreProductsListRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/products/search.ts
+++ b/packages/medusa/src/api/routes/store/products/search.ts
@@ -39,11 +39,7 @@ import { validator } from "../../../../utils/validator"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             hits:
- *               type: array
- *               description: Array of results. The format of the items depends on the search engine installed on the server.
+ *           $ref: "#/components/schemas/StorePostSearchRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/regions/get-region.ts
+++ b/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
- *           properties:
- *             region:
- *               $ref: "#/components/schemas/Region"
+ *           $ref: "#/components/schemas/StoreRegionsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/regions/index.ts
+++ b/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
 }
--- a/packages/medusa/src/api/routes/store/regions/list-regions.ts
+++ b/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
- *           properties:
- *             regions:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/Region"
+ *           $ref: "#/components/schemas/StoreRegionsListRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/return-reasons/get-reason.ts
+++ b/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
- *           properties:
- *             return_reason:
- *               $ref: "#/components/schemas/ReturnReason"
+ *           $ref: "#/components/schemas/StoreReturnReasonsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/return-reasons/index.ts
+++ b/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
 }
--- a/packages/medusa/src/api/routes/store/return-reasons/list-reasons.ts
+++ b/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
- *           properties:
- *             return_reasons:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/ReturnReason"
+ *           $ref: "#/components/schemas/StoreReturnReasonsListRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/returns/create-return.ts
+++ b/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
- *           properties:
- *             return:
- *               $ref: "#/components/schemas/Return"
+ *           $ref: "#/components/schemas/StoreReturnsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/returns/index.ts
+++ b/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
 }
--- a/packages/medusa/src/api/routes/store/shipping-options/index.ts
+++ b/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[]
 }
--- a/packages/medusa/src/api/routes/store/shipping-options/list-options.ts
+++ b/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
- *           properties:
- *             shipping_options:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/ShippingOption"
+ *           $ref: "#/components/schemas/StoreShippingOptionsListRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/shipping-options/list-shipping-options.ts
+++ b/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
- *           properties:
- *             shipping_options:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/ShippingOption"
+ *           $ref: "#/components/schemas/StoreShippingOptionsListRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/swaps/create-swap.ts
+++ b/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
- *           properties:
- *             swap:
- *               $ref: "#/components/schemas/Swap"
+ *           $ref: "#/components/schemas/StoreSwapsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/swaps/get-swap-by-cart.ts
+++ b/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
- *           properties:
- *             swap:
- *               $ref: "#/components/schemas/Swap"
+ *           $ref: "#/components/schemas/StoreSwapsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/swaps/index.ts
+++ b/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
 }
--- a/packages/medusa/src/api/routes/store/variants/get-variant.ts
+++ b/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
- *           properties:
- *             variant:
- *               allOf:
- *                 - $ref: "#/components/schemas/ProductVariant"
- *                 - $ref: "#/components/schemas/ProductVariantPricesFields"
+ *           $ref: "#/components/schemas/StoreVariantsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/variants/index.ts
+++ b/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[]
 }

--- a/packages/medusa/src/api/routes/store/variants/list-variants.ts
+++ b/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
- *           properties:
- *             variants:
- *               type: array
- *               items:
- *                 allOf:
- *                   - $ref: "#/components/schemas/ProductVariant"
- *                   - $ref: "#/components/schemas/ProductVariantPricesFields"
+ *           $ref: "#/components/schemas/StoreVariantsListRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/models/product-variant.ts
+++ b/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
- */
--- a/packages/medusa/src/types/pricing.ts
+++ b/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[]
 }