chore(oas): replace response with $ref class JSDoc (Store A-PAY)

2023-01-16 11:19:15 -05:00
parent 8c08d00319
commit b791e34589
50 changed files with 195 additions and 224 deletions
--- a/packages/medusa/src/api/routes/store/auth/create-session.ts
+++ b/packages/medusa/src/api/routes/store/auth/create-session.ts
@@ -43,10 +43,7 @@ import { validator } from "../../../../utils/validator"
 *    content:
 *      application/json:
 *        schema:
- *          type: object
- *          properties:
- *            customer:
- *              $ref: "#/components/schemas/Customer"
+ *          $ref: "#/components/schemas/StoreAuthRes"
 *  "400":
 *    $ref: "#/components/responses/400_error"
 *  "401":
--- a/packages/medusa/src/api/routes/store/auth/exists.ts
+++ b/packages/medusa/src/api/routes/store/auth/exists.ts
@@ -1,4 +1,5 @@
 import CustomerService from "../../../../services/customer"
+
 /**
 * @oas [get] /auth/{email}
 * operationId: "GetAuthEmail"
@@ -32,11 +33,7 @@ import CustomerService from "../../../../services/customer"
 *    content:
 *      application/json:
 *        schema:
- *          type: object
- *          properties:
- *            exists:
- *              type: boolean
- *              description: Whether email exists or not.
+ *          $ref: "#/components/schemas/StoreGetAuthEmailRes"
 *  "400":
 *    $ref: "#/components/responses/400_error"
 *  "404":
--- a/packages/medusa/src/api/routes/store/auth/get-session.ts
+++ b/packages/medusa/src/api/routes/store/auth/get-session.ts
@@ -32,10 +32,7 @@ import CustomerService from "../../../../services/customer"
 *    content:
 *      application/json:
 *        schema:
- *          type: object
- *          properties:
- *            customer:
- *              $ref: "#/components/schemas/Customer"
+ *          $ref: "#/components/schemas/StoreAuthRes"
 *  "400":
 *    $ref: "#/components/responses/400_error"
 *  "401":
--- a/packages/medusa/src/api/routes/store/auth/index.ts
+++ b/packages/medusa/src/api/routes/store/auth/index.ts
@@ -19,10 +19,25 @@ export default (app) => {
  return app
 }

+/**
+ * @schema StoreAuthRes
+ * type: object
+ * properties:
+ *   customer:
+ *     $ref: "#/components/schemas/Customer"
+ */
 export type StoreAuthRes = {
  customer: Customer
 }

+/**
+ * @schema StoreGetAuthEmailRes
+ * type: object
+ * properties:
+ *   exists:
+ *     type: boolean
+ *     description: Whether email exists or not.
+ */
 export type StoreGetAuthEmailRes = {
  exists: boolean
 }
--- a/packages/medusa/src/api/routes/store/carts/add-shipping-method.ts
+++ b/packages/medusa/src/api/routes/store/carts/add-shipping-method.ts
@@ -42,10 +42,7 @@ import { validator } from "../../../../utils/validator"
 *    content:
 *      application/json:
 *        schema:
- *          type: object
- *          properties:
- *            cart:
- *              $ref: "#/components/schemas/Cart"
+ *          $ref: "#/components/schemas/StoreCartsRes"
 *  "400":
 *    $ref: "#/components/responses/400_error"
 *  "404":
--- a/packages/medusa/src/api/routes/store/carts/calculate-taxes.ts
+++ b/packages/medusa/src/api/routes/store/carts/calculate-taxes.ts
@@ -24,10 +24,7 @@ import { IdempotencyKey } from "../../../../models/idempotency-key"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             cart:
- *               $ref: "#/components/schemas/Cart"
+ *           $ref: "#/components/schemas/StoreCartsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/carts/complete-cart.ts
+++ b/packages/medusa/src/api/routes/store/carts/complete-cart.ts
@@ -40,31 +40,7 @@ import { IdempotencyKeyService } from "../../../../services"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             type:
- *               type: string
- *               description: The type of the data property.
- *               enum: [order, cart, swap]
- *             data:
- *               type: object
- *               description: The data of the result object. Its type depends on the type field.
- *               oneOf:
- *                 - type: object
- *                   description: Cart was successfully authorized and order was placed successfully.
- *                   properties:
- *                     order:
- *                       $ref: "#/components/schemas/Order"
- *                 - type: object
- *                   description: Cart was successfully authorized but requires further actions.
- *                   properties:
- *                     cart:
- *                       $ref: "#/components/schemas/Cart"
- *                 - type: object
- *                   description: When cart is used for a swap and it has been completed successfully.
- *                   properties:
- *                     cart:
- *                       $ref: "#/components/schemas/Swap"
+ *           $ref: "#/components/schemas/StoreCompleteCartRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/carts/create-cart.ts
+++ b/packages/medusa/src/api/routes/store/carts/create-cart.ts
@@ -59,10 +59,7 @@ import PublishableAPIKeysFeatureFlag from "../../../../loaders/feature-flags/pub
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             cart:
- *               $ref: "#/components/schemas/Cart"
+ *           $ref: "#/components/schemas/StoreCartsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/carts/create-line-item/index.ts
+++ b/packages/medusa/src/api/routes/store/carts/create-line-item/index.ts
@@ -53,10 +53,7 @@ import {
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             cart:
- *               $ref: "#/components/schemas/Cart"
+ *           $ref: "#/components/schemas/StoreCartsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/carts/create-payment-sessions.ts
+++ b/packages/medusa/src/api/routes/store/carts/create-payment-sessions.ts
@@ -32,10 +32,7 @@ import IdempotencyKeyService from "../../../../services/idempotency-key"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             cart:
- *               $ref: "#/components/schemas/Cart"
+ *           $ref: "#/components/schemas/StoreCartsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/carts/delete-discount.ts
+++ b/packages/medusa/src/api/routes/store/carts/delete-discount.ts
@@ -32,10 +32,7 @@ import { CartService } from "../../../../services"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             cart:
- *               $ref: "#/components/schemas/Cart"
+ *           $ref: "#/components/schemas/StoreCartsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/carts/delete-line-item.ts
+++ b/packages/medusa/src/api/routes/store/carts/delete-line-item.ts
@@ -32,10 +32,7 @@ import { CartService } from "../../../../services"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             cart:
- *               $ref: "#/components/schemas/Cart"
+ *           $ref: "#/components/schemas/StoreCartsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/carts/delete-payment-session.ts
+++ b/packages/medusa/src/api/routes/store/carts/delete-payment-session.ts
@@ -32,10 +32,7 @@ import { EntityManager } from "typeorm"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             cart:
- *               $ref: "#/components/schemas/Cart"
+ *           $ref: "#/components/schemas/StoreCartsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/carts/get-cart.ts
+++ b/packages/medusa/src/api/routes/store/carts/get-cart.ts
@@ -29,10 +29,7 @@ import { CartService } from "../../../../services"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             cart:
- *               $ref: "#/components/schemas/Cart"
+ *           $ref: "#/components/schemas/StoreCartsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/carts/index.ts
+++ b/packages/medusa/src/api/routes/store/carts/index.ts
@@ -156,10 +156,42 @@ export const defaultStoreCartRelations = [
  "discounts.rule",
 ]

+/**
+ * @schema StoreCartsRes
+ * type: object
+ * properties:
+ *   cart:
+ *     $ref: "#/components/schemas/Cart"
+ */
 export type StoreCartsRes = {
  cart: Omit<Cart, "refundable_amount" | "refunded_total">
 }

+/**
+ * @schema StoreCompleteCartRes
+ * type: object
+ * properties:
+ *   type:
+ *     type: string
+ *     description: The type of the data property.
+ *     enum: [order, cart, swap]
+ *   data:
+ *     type: object
+ *     description: The data of the result object. Its type depends on the type field.
+ *     oneOf:
+ *       - type: object
+ *         allOf:
+ *           - description: Cart was successfully authorized and order was placed successfully.
+ *           - $ref: "#/components/schemas/Order"
+ *       - type: object
+ *         allOf:
+ *           - description: Cart was successfully authorized but requires further actions.
+ *           - $ref: "#/components/schemas/Cart"
+ *       - type: object
+ *         allOf:
+ *           - description: When cart is used for a swap and it has been completed successfully.
+ *           - $ref: "#/components/schemas/Swap"
+ */
 export type StoreCompleteCartRes =
  | {
      type: "cart"
--- a/packages/medusa/src/api/routes/store/carts/refresh-payment-session.ts
+++ b/packages/medusa/src/api/routes/store/carts/refresh-payment-session.ts
@@ -31,10 +31,7 @@ import { EntityManager } from "typeorm"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             cart:
- *               $ref: "#/components/schemas/Cart"
+ *           $ref: "#/components/schemas/StoreCartsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/carts/set-payment-session.ts
+++ b/packages/medusa/src/api/routes/store/carts/set-payment-session.ts
@@ -41,10 +41,7 @@ import { validator } from "../../../../utils/validator"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             cart:
- *               $ref: "#/components/schemas/Cart"
+ *           $ref: "#/components/schemas/StoreCartsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/carts/update-cart.ts
+++ b/packages/medusa/src/api/routes/store/carts/update-cart.ts
@@ -55,10 +55,7 @@ import { IsType } from "../../../../utils/validators/is-type"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             cart:
- *               $ref: "#/components/schemas/Cart"
+ *           $ref: "#/components/schemas/StoreCartsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/carts/update-line-item.ts
+++ b/packages/medusa/src/api/routes/store/carts/update-line-item.ts
@@ -42,10 +42,7 @@ import { validator } from "../../../../utils/validator"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             cart:
- *               $ref: "#/components/schemas/Cart"
+ *           $ref: "#/components/schemas/StoreCartsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/carts/update-payment-session.ts
+++ b/packages/medusa/src/api/routes/store/carts/update-payment-session.ts
@@ -43,10 +43,7 @@ import { EntityManager } from "typeorm"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             cart:
- *               $ref: "#/components/schemas/Cart"
+ *           $ref: "#/components/schemas/StoreCartsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/collections/get-collection.ts
+++ b/packages/medusa/src/api/routes/store/collections/get-collection.ts
@@ -29,10 +29,7 @@ import ProductCollectionService from "../../../../services/product-collection"
 *    content:
 *      application/json:
 *        schema:
- *          type: object
- *          properties:
- *            collection:
- *              $ref: "#/components/schemas/ProductCollection"
+ *          $ref: "#/components/schemas/StoreCollectionsRes"
 *  "400":
 *    $ref: "#/components/responses/400_error"
 *  "404":
--- a/packages/medusa/src/api/routes/store/collections/index.ts
+++ b/packages/medusa/src/api/routes/store/collections/index.ts
@@ -34,10 +34,35 @@ export const allowedFields = [
  ...defaultStoreCollectionRelations,
 ]

+/**
+ * @schema StoreCollectionsListRes
+ * type: object
+ * properties:
+ *   collections:
+ *      type: array
+ *      items:
+ *        $ref: "#/components/schemas/ProductCollection"
+ *   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 StoreCollectionsListRes = PaginatedResponse & {
  collections: ProductCollection[]
 }

+/**
+ * @schema StoreCollectionsRes
+ * type: object
+ * properties:
+ *   collection:
+ *     $ref: "#/components/schemas/ProductCollection"
+ */
 export type StoreCollectionsRes = {
  collection: ProductCollection
 }
--- a/packages/medusa/src/api/routes/store/collections/list-collections.ts
+++ b/packages/medusa/src/api/routes/store/collections/list-collections.ts
@@ -78,21 +78,7 @@ import { Type } from "class-transformer"
 *    content:
 *      application/json:
 *        schema:
- *          type: object
- *          properties:
- *            collections:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/ProductCollection"
- *            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/StoreCollectionsListRes"
 *  "400":
 *    $ref: "#/components/responses/400_error"
 *  "404":
--- a/packages/medusa/src/api/routes/store/customers/create-address.ts
+++ b/packages/medusa/src/api/routes/store/customers/create-address.ts
@@ -68,10 +68,7 @@ import { validator } from "../../../../utils/validator"
 *    content:
 *      application/json:
 *        schema:
- *          type: object
- *          properties:
- *            customer:
- *              $ref: "#/components/schemas/Customer"
+ *          $ref: "#/components/schemas/StoreCustomersRes"
 *  "400":
 *    $ref: "#/components/responses/400_error"
 *  "401":
--- a/packages/medusa/src/api/routes/store/customers/create-customer.ts
+++ b/packages/medusa/src/api/routes/store/customers/create-customer.ts
@@ -51,10 +51,7 @@ import { validator } from "../../../../utils/validator"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             customer:
- *               $ref: "#/components/schemas/Customer"
+ *           $ref: "#/components/schemas/StoreCustomersRes"
 *   422:
 *     description: A customer with the same email exists
 *     content:
--- a/packages/medusa/src/api/routes/store/customers/delete-address.ts
+++ b/packages/medusa/src/api/routes/store/customers/delete-address.ts
@@ -37,10 +37,7 @@ import CustomerService from "../../../../services/customer"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             customer:
- *               $ref: "#/components/schemas/Customer"
+ *           $ref: "#/components/schemas/StoreCustomersRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/store/customers/get-customer.ts
+++ b/packages/medusa/src/api/routes/store/customers/get-customer.ts
@@ -33,10 +33,7 @@ import CustomerService from "../../../../services/customer"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             customer:
- *               $ref: "#/components/schemas/Customer"
+ *           $ref: "#/components/schemas/StoreCustomersRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/store/customers/get-payment-methods.ts
+++ b/packages/medusa/src/api/routes/store/customers/get-payment-methods.ts
@@ -1,7 +1,6 @@
 import { Customer } from "../../../.."
 import CustomerService from "../../../../services/customer"
 import PaymentProviderService from "../../../../services/payment-provider"
-import StoreService from "../../../../services/store"
 import { PaymentProvider } from "../../../../models"

 /**
@@ -36,18 +35,7 @@ import { PaymentProvider } from "../../../../models"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             payment_methods:
- *               type: array
- *               items:
- *                 properties:
- *                   provider_id:
- *                     type: string
- *                     description: The id of the Payment Provider where the payment method is saved.
- *                   data:
- *                     type: object
- *                     description: The data needed for the Payment Provider to use the saved payment method.
+ *           $ref: "#/components/schemas/StoreCustomersListPaymentMethodsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/store/customers/index.ts
+++ b/packages/medusa/src/api/routes/store/customers/index.ts
@@ -1,10 +1,7 @@
 import { Router } from "express"
-import { Customer, Order, StorePostCustomersReq } from "../../../.."
+import { Customer, Order } from "../../../.."
 import { PaginatedResponse } from "../../../../types/common"
-import middlewares, {
-  transformBody,
-  transformQuery,
-} from "../../../middlewares"
+import middlewares, { transformQuery } from "../../../middlewares"
 import {
  defaultStoreOrdersFields,
  defaultStoreOrdersRelations,
@@ -114,14 +111,55 @@ export const allowedStoreCustomersFields = [
  "metadata",
 ]

+/**
+ * @schema StoreCustomersRes
+ * type: object
+ * properties:
+ *   customer:
+ *     $ref: "#/components/schemas/Customer"
+ */
 export type StoreCustomersRes = {
  customer: Omit<Customer, "password_hash">
 }

+/**
+ * @schema StoreCustomersListOrdersRes
+ * type: object
+ * properties:
+ *   orders:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/Order"
+ *   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 StoreCustomersListOrdersRes = PaginatedResponse & {
  orders: Order[]
 }

+/**
+ * @schema StoreCustomersListPaymentMethodsRes
+ * type: object
+ * properties:
+ *   payment_methods:
+ *     type: array
+ *     items:
+ *       type: object
+ *       properties:
+ *         provider_id:
+ *           type: string
+ *           description: The id of the Payment Provider where the payment method is saved.
+ *         data:
+ *           type: object
+ *           description: The data needed for the Payment Provider to use the saved payment method.
+ */
 export type StoreCustomersListPaymentMethodsRes = {
  payment_methods: {
    provider_id: string
--- a/packages/medusa/src/api/routes/store/customers/list-orders.ts
+++ b/packages/medusa/src/api/routes/store/customers/list-orders.ts
@@ -163,21 +163,7 @@ import { DateComparisonOperator } from "../../../../types/common"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             orders:
- *               type: array
- *               items:
- *                 $ref: "#/components/schemas/Order"
- *             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/StoreCustomersListOrdersRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/store/customers/reset-password.ts
+++ b/packages/medusa/src/api/routes/store/customers/reset-password.ts
@@ -47,10 +47,7 @@ import { EntityManager } from "typeorm"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             customer:
- *               $ref: "#/components/schemas/Customer"
+ *           $ref: "#/components/schemas/StoreCustomersRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/store/customers/update-address.ts
+++ b/packages/medusa/src/api/routes/store/customers/update-address.ts
@@ -50,10 +50,7 @@ import { validator } from "../../../../utils/validator"
 *    content:
 *      application/json:
 *        schema:
- *          type: object
- *          properties:
- *            customer:
- *              $ref: "#/components/schemas/Customer"
+ *          $ref: "#/components/schemas/StoreCustomersRes"
 *  "400":
 *    $ref: "#/components/responses/400_error"
 *  "401":
--- a/packages/medusa/src/api/routes/store/customers/update-customer.ts
+++ b/packages/medusa/src/api/routes/store/customers/update-customer.ts
@@ -50,10 +50,7 @@ import { IsType } from "../../../../utils/validators/is-type"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             customer:
- *               $ref: "#/components/schemas/Customer"
+ *           $ref: "#/components/schemas/StoreCustomersRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/store/gift-cards/get-gift-card.ts
+++ b/packages/medusa/src/api/routes/store/gift-cards/get-gift-card.ts
@@ -31,10 +31,7 @@ import GiftCardService from "../../../../services/gift-card"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             gift_card:
- *               $ref: "#/components/schemas/GiftCard"
+ *           $ref: "#/components/schemas/StoreGiftCardsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/gift-cards/index.ts
+++ b/packages/medusa/src/api/routes/store/gift-cards/index.ts
@@ -25,6 +25,13 @@ export const allowedStoreGiftCardRelations = ["region"]

 export const allowedStoreGiftCardFields = ["id", "code", "value", "balance"]

+/**
+ * @schema StoreGiftCardsRes
+ * type: object
+ * properties:
+ *   gift_card:
+ *     $ref: "#/components/schemas/GiftCard"
+ */
 export type StoreGiftCardsRes = {
  gift_card: GiftCard
 }
--- a/packages/medusa/src/api/routes/store/order-edits/complete-order-edit.ts
+++ b/packages/medusa/src/api/routes/store/order-edits/complete-order-edit.ts
@@ -5,7 +5,7 @@ import { OrderEditStatus, PaymentCollectionStatus } from "../../../../models"
 import { OrderEditService, PaymentProviderService } from "../../../../services"
 import {
  defaultStoreOrderEditFields,
-  defaultStoreOrderEditRelations
+  defaultStoreOrderEditRelations,
 } from "../../../../types/order-edit"

 /**
@@ -37,10 +37,7 @@ import {
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             order_edit:
- *               $ref: "#/components/schemas/OrderEdit"
+ *           $ref: "#/components/schemas/StoreOrderEditsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/store/order-edits/decline-order-edit.ts
+++ b/packages/medusa/src/api/routes/store/order-edits/decline-order-edit.ts
@@ -4,7 +4,7 @@ import { EntityManager } from "typeorm"
 import { OrderEditService } from "../../../../services"
 import {
  defaultStoreOrderEditFields,
-  defaultStoreOrderEditRelations
+  defaultStoreOrderEditRelations,
 } from "../../../../types/order-edit"

 /**
@@ -41,10 +41,7 @@ import {
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             order_edit:
- *               $ref: "#/components/schemas/OrderEdit"
+ *           $ref: "#/components/schemas/StoreOrderEditsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/store/order-edits/get-order-edit.ts
+++ b/packages/medusa/src/api/routes/store/order-edits/get-order-edit.ts
@@ -30,10 +30,7 @@ import { OrderEditService } from "../../../../services"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             order_edit:
- *               $ref: "#/components/schemas/OrderEdit"
+ *           $ref: "#/components/schemas/StoreOrderEditsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/store/order-edits/index.ts
+++ b/packages/medusa/src/api/routes/store/order-edits/index.ts
@@ -41,6 +41,13 @@ export default (app) => {
  return app
 }

+/**
+ * @schema StoreOrderEditsRes
+ * type: object
+ * properties:
+ *   order_edit:
+ *     $ref: "#/components/schemas/OrderEdit"
+ */
 export type StoreOrderEditsRes = {
  order_edit: Omit<
    OrderEdit,
--- a/packages/medusa/src/api/routes/store/orders/get-order-by-cart.ts
+++ b/packages/medusa/src/api/routes/store/orders/get-order-by-cart.ts
@@ -31,10 +31,7 @@ import { OrderService } from "../../../../services"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             order:
- *               $ref: "#/components/schemas/Order"
+ *           $ref: "#/components/schemas/StoreOrdersRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/orders/get-order.ts
+++ b/packages/medusa/src/api/routes/store/orders/get-order.ts
@@ -31,10 +31,7 @@ import { OrderService } from "../../../../services"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             order:
- *               $ref: "#/components/schemas/Order"
+ *           $ref: "#/components/schemas/StoreOrdersRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/orders/index.ts
+++ b/packages/medusa/src/api/routes/store/orders/index.ts
@@ -83,6 +83,13 @@ export const defaultStoreOrdersFields = [
  "total",
 ] as (keyof Order)[]

+/**
+ * @schema StoreOrdersRes
+ * type: object
+ * properties:
+ *   order:
+ *     $ref: "#/components/schemas/Order"
+ */
 export type StoreOrdersRes = {
  order: Order
 }
--- a/packages/medusa/src/api/routes/store/orders/lookup-order.ts
+++ b/packages/medusa/src/api/routes/store/orders/lookup-order.ts
@@ -63,10 +63,7 @@ import { validator } from "../../../../utils/validator"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             order:
- *               $ref: "#/components/schemas/Order"
+ *           $ref: "#/components/schemas/StoreOrdersRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":
--- a/packages/medusa/src/api/routes/store/payment-collections/authorize-batch-payment-sessions.ts
+++ b/packages/medusa/src/api/routes/store/payment-collections/authorize-batch-payment-sessions.ts
@@ -40,9 +40,7 @@ import { PaymentCollectionService } from "../../../../services"
 *     content:
 *       application/json:
 *         schema:
- *           properties:
- *             payment_collection:
- *               $ref: "#/components/schemas/PaymentCollection"
+ *           $ref: "#/components/schemas/StorePaymentCollectionsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/store/payment-collections/authorize-payment-session.ts
+++ b/packages/medusa/src/api/routes/store/payment-collections/authorize-payment-session.ts
@@ -37,9 +37,7 @@ import { PaymentCollectionService } from "../../../../services"
 *     content:
 *       application/json:
 *         schema:
- *           properties:
- *             payment_session:
- *               $ref: "#/components/schemas/PaymentSession"
+ *           $ref: "#/components/schemas/StorePaymentCollectionsSessionRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/store/payment-collections/get-payment-collection.ts
+++ b/packages/medusa/src/api/routes/store/payment-collections/get-payment-collection.ts
@@ -37,10 +37,7 @@ import { FindParams } from "../../../../types/common"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             payment_collection:
- *               $ref: "#/components/schemas/PaymentCollection"
+ *           $ref: "#/components/schemas/StorePaymentCollectionsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/store/payment-collections/index.ts
+++ b/packages/medusa/src/api/routes/store/payment-collections/index.ts
@@ -71,10 +71,24 @@ export const defaultPaymentCollectionFields = [

 export const defaulPaymentCollectionRelations = ["region", "payment_sessions"]

+/**
+ * @schema StorePaymentCollectionsRes
+ * type: object
+ * properties:
+ *   payment_collection:
+ *     $ref: "#/components/schemas/PaymentCollection"
+ */
 export type StorePaymentCollectionsRes = {
  payment_collection: PaymentCollection
 }

+/**
+ * @schema StorePaymentCollectionsSessionRes
+ * type: object
+ * properties:
+ *   payment_session:
+ *     $ref: "#/components/schemas/PaymentSession"
+ */
 export type StorePaymentCollectionsSessionRes = {
  payment_session: PaymentSession
 }
--- a/packages/medusa/src/api/routes/store/payment-collections/manage-batch-payment-sessions.ts
+++ b/packages/medusa/src/api/routes/store/payment-collections/manage-batch-payment-sessions.ts
@@ -68,9 +68,7 @@ import { PaymentCollectionService } from "../../../../services"
 *     content:
 *       application/json:
 *         schema:
- *           properties:
- *             payment_collection:
- *               $ref: "#/components/schemas/PaymentCollection"
+ *           $ref: "#/components/schemas/StorePaymentCollectionsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/store/payment-collections/manage-payment-session.ts
+++ b/packages/medusa/src/api/routes/store/payment-collections/manage-payment-session.ts
@@ -47,9 +47,7 @@ import { PaymentCollectionService } from "../../../../services"
 *     content:
 *       application/json:
 *         schema:
- *           properties:
- *             payment_collection:
- *               $ref: "#/components/schemas/PaymentCollection"
+ *           $ref: "#/components/schemas/StorePaymentCollectionsRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "401":
--- a/packages/medusa/src/api/routes/store/payment-collections/refresh-payment-session.ts
+++ b/packages/medusa/src/api/routes/store/payment-collections/refresh-payment-session.ts
@@ -32,10 +32,7 @@ import { PaymentCollectionService } from "../../../../services"
 *     content:
 *       application/json:
 *         schema:
- *           type: object
- *           properties:
- *             payment_session:
- *               $ref: "#/components/schemas/PaymentSession"
+ *           $ref: "#/components/schemas/StorePaymentCollectionsSessionRes"
 *   "400":
 *     $ref: "#/components/responses/400_error"
 *   "404":