chore(oas): replace response with $ref class JSDoc (Admin O-PRI) (#3018)

### Scope Admin routes directories O to PRI. ### 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.
medusajs · Jan 13, 2023 · cdcbc06 · cdcbc06
1 parent 9dbccd9
commit cdcbc06
Show file tree

Hide file tree

Showing 59 changed files with 303 additions and 343 deletions.
diff --git a/packages/medusa/src/api/routes/admin/order-edits/add-line-item.ts b/packages/medusa/src/api/routes/admin/order-edits/add-line-item.ts
@@ -53,10 +53,7 @@ import {
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             order_edit:
- *               $ref: "#/components/schemas/OrderEdit"
+ *           $ref: "#/components/schemas/AdminOrderEditsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

diff --git a/packages/medusa/src/api/routes/admin/order-edits/cancel-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/cancel-order-edit.ts
@@ -3,7 +3,7 @@ import { EntityManager } from "typeorm"
 import { OrderEditService } from "../../../../services"
 import {
   defaultOrderEditFields,
-  defaultOrderEditRelations
+  defaultOrderEditRelations,
 } 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/AdminOrderEditsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

diff --git a/packages/medusa/src/api/routes/admin/order-edits/confirm-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/confirm-order-edit.ts
@@ -3,7 +3,7 @@ import { EntityManager } from "typeorm"
 import { OrderEditService } from "../../../../services"
 import {
   defaultOrderEditFields,
-  defaultOrderEditRelations
+  defaultOrderEditRelations,
 } 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/AdminOrderEditsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

diff --git a/packages/medusa/src/api/routes/admin/order-edits/create-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/create-order-edit.ts
@@ -4,7 +4,7 @@ import { EntityManager } from "typeorm"
 import { OrderEditService } from "../../../../services"
 import {
   defaultOrderEditFields,
-  defaultOrderEditRelations
+  defaultOrderEditRelations,
 } from "../../../../types/order-edit"
 
 /**
@@ -47,10 +47,7 @@ import {
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             order_edit:
- *               $ref: "#/components/schemas/OrderEdit"
+ *           $ref: "#/components/schemas/AdminOrderEditsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

diff --git a/packages/medusa/src/api/routes/admin/order-edits/delete-line-item.ts b/packages/medusa/src/api/routes/admin/order-edits/delete-line-item.ts
@@ -42,10 +42,7 @@ import {
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             order_edit:
- *               $ref: "#/components/schemas/OrderEdit"
+ *           $ref: "#/components/schemas/AdminOrderEditsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

diff --git a/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit-item-change.ts b/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit-item-change.ts
@@ -37,19 +37,7 @@ import { OrderEditService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             id:
- *               type: string
- *               description: The ID of the deleted Order Edit Item Change.
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               format: item_change
- *             deleted:
- *               type: boolean
- *               description: Whether or not the Order Edit Item Change was deleted.
- *               default: true
+ *           $ref: "#/components/schemas/AdminOrderEditItemChangeDeleteRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  */

diff --git a/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/delete-order-edit.ts
@@ -36,19 +36,7 @@ import { OrderEditService } from "../../../../services"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             id:
- *               type: string
- *               description: The ID of the deleted Order Edit.
- *             object:
- *               type: string
- *               description: The type of the object that was deleted.
- *               format: order_edit
- *             deleted:
- *               type: boolean
- *               description: Whether or not the Order Edit was deleted.
- *               default: true
+ *           $ref: "#/components/schemas/AdminOrderEditDeleteRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  */

diff --git a/packages/medusa/src/api/routes/admin/order-edits/get-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/get-order-edit.ts
@@ -39,10 +39,7 @@ import { FindParams } from "../../../../types/common"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             order_edit:
- *               $ref: "#/components/schemas/OrderEdit"
+ *           $ref: "#/components/schemas/AdminOrderEditsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

diff --git a/packages/medusa/src/api/routes/admin/order-edits/index.ts b/packages/medusa/src/api/routes/admin/order-edits/index.ts
@@ -98,13 +98,73 @@ export default (app) => {
   return app
 }
 
+/**
+ * @schema AdminOrderEditsRes
+ * type: object
+ * properties:
+ *   order_edit:
+ *     $ref: "#/components/schemas/OrderEdit"
+ */
 export type AdminOrderEditsRes = {
   order_edit: OrderEdit
 }
+
+/**
+ * @schema AdminOrderEditsListRes
+ * type: object
+ * properties:
+ *   order_edits:
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/OrderEdit"
+ *   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 AdminOrderEditsListRes = PaginatedResponse & {
   order_edits: OrderEdit[]
 }
+
+/**
+ * @schema AdminOrderEditDeleteRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted Order Edit.
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: order_edit
+ *   deleted:
+ *     type: boolean
+ *     description: Whether or not the Order Edit was deleted.
+ *     default: true
+ */
 export type AdminOrderEditDeleteRes = DeleteResponse
+
+/**
+ * @schema AdminOrderEditItemChangeDeleteRes
+ * type: object
+ * properties:
+ *   id:
+ *     type: string
+ *     description: The ID of the deleted Order Edit Item Change.
+ *   object:
+ *     type: string
+ *     description: The type of the object that was deleted.
+ *     default: item_change
+ *   deleted:
+ *     type: boolean
+ *     description: Whether or not the Order Edit Item Change was deleted.
+ *     default: true
+ */
 export type AdminOrderEditItemChangeDeleteRes = {
   id: string
   object: "item_change"

diff --git a/packages/medusa/src/api/routes/admin/order-edits/list-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/list-order-edit.ts
@@ -43,20 +43,7 @@ import { IsOptional, IsString } from "class-validator"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             order_edits:
- *               type: array
- *               $ref: "#/components/schemas/OrderEdit"
- *             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/AdminOrderEditsListRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

diff --git a/packages/medusa/src/api/routes/admin/order-edits/request-confirmation.ts b/packages/medusa/src/api/routes/admin/order-edits/request-confirmation.ts
@@ -4,11 +4,11 @@ import { PaymentCollectionType } from "../../../../models"
 import {
   OrderEditService,
   OrderService,
-  PaymentCollectionService
+  PaymentCollectionService,
 } from "../../../../services"
 import {
   defaultOrderEditFields,
-  defaultOrderEditRelations
+  defaultOrderEditRelations,
 } from "../../../../types/order-edit"
 
 /**
@@ -46,10 +46,7 @@ import {
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             order_edit:
- *               $ref: "#/components/schemas/OrderEdit"
+ *           $ref: "#/components/schemas/AdminOrderEditsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

diff --git a/packages/medusa/src/api/routes/admin/order-edits/update-order-edit-line-item.ts b/packages/medusa/src/api/routes/admin/order-edits/update-order-edit-line-item.ts
@@ -52,10 +52,7 @@ import {
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             order_edit:
- *               $ref: "#/components/schemas/OrderEdit"
+ *           $ref: "#/components/schemas/AdminOrderEditsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

diff --git a/packages/medusa/src/api/routes/admin/order-edits/update-order-edit.ts b/packages/medusa/src/api/routes/admin/order-edits/update-order-edit.ts
@@ -54,10 +54,7 @@ import {
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             order_edit:
- *               $ref: "#/components/schemas/OrderEdit"
+ *           $ref: "#/components/schemas/AdminOrderEditsRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

diff --git a/packages/medusa/src/api/routes/admin/orders/add-shipping-method.ts b/packages/medusa/src/api/routes/admin/orders/add-shipping-method.ts
@@ -57,10 +57,7 @@ import { EntityManager } from "typeorm"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             order:
- *               $ref: "#/components/schemas/Order"
+ *           $ref: "#/components/schemas/AdminOrdersRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

diff --git a/packages/medusa/src/api/routes/admin/orders/archive-order.ts b/packages/medusa/src/api/routes/admin/orders/archive-order.ts
@@ -36,10 +36,7 @@ import { EntityManager } from "typeorm"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             order:
- *               $ref: "#/components/schemas/Order"
+ *           $ref: "#/components/schemas/AdminOrdersRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

diff --git a/packages/medusa/src/api/routes/admin/orders/cancel-claim.ts b/packages/medusa/src/api/routes/admin/orders/cancel-claim.ts
@@ -40,10 +40,7 @@ import { MedusaError } from "medusa-core-utils"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             order:
- *               $ref: "#/components/schemas/Order"
+ *           $ref: "#/components/schemas/AdminOrdersRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

diff --git a/packages/medusa/src/api/routes/admin/orders/cancel-fulfillment-claim.ts b/packages/medusa/src/api/routes/admin/orders/cancel-fulfillment-claim.ts
@@ -45,10 +45,7 @@ import { MedusaError } from "medusa-core-utils"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             order:
- *               $ref: "#/components/schemas/Order"
+ *           $ref: "#/components/schemas/AdminOrdersRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

diff --git a/packages/medusa/src/api/routes/admin/orders/cancel-fulfillment-swap.ts b/packages/medusa/src/api/routes/admin/orders/cancel-fulfillment-swap.ts
@@ -45,10 +45,7 @@ import { MedusaError } from "medusa-core-utils"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             order:
- *               $ref: "#/components/schemas/Order"
+ *           $ref: "#/components/schemas/AdminOrdersRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

diff --git a/packages/medusa/src/api/routes/admin/orders/cancel-fulfillment.ts b/packages/medusa/src/api/routes/admin/orders/cancel-fulfillment.ts
@@ -45,10 +45,7 @@ import { Fulfillment } from "../../../../models"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             order:
- *               $ref: "#/components/schemas/Order"
+ *           $ref: "#/components/schemas/AdminOrdersRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

diff --git a/packages/medusa/src/api/routes/admin/orders/cancel-order.ts b/packages/medusa/src/api/routes/admin/orders/cancel-order.ts
@@ -38,10 +38,7 @@ import { EntityManager } from "typeorm"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             order:
- *               $ref: "#/components/schemas/Order"
+ *           $ref: "#/components/schemas/AdminOrdersRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

diff --git a/packages/medusa/src/api/routes/admin/orders/cancel-swap.ts b/packages/medusa/src/api/routes/admin/orders/cancel-swap.ts
@@ -40,10 +40,7 @@ import { MedusaError } from "medusa-core-utils"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             order:
- *               $ref: "#/components/schemas/Order"
+ *           $ref: "#/components/schemas/AdminOrdersRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":

diff --git a/packages/medusa/src/api/routes/admin/orders/capture-payment.ts b/packages/medusa/src/api/routes/admin/orders/capture-payment.ts
@@ -38,10 +38,7 @@ import { EntityManager } from "typeorm"
  *     content:
  *       application/json:
  *         schema:
- *           type: object
- *           properties:
- *             order:
- *               $ref: "#/components/schemas/Order"
+ *           $ref: "#/components/schemas/AdminOrdersRes"
  *   "400":
  *     $ref: "#/components/responses/400_error"
  *   "401":