chore(docs): Refactor API Reference (#1883)

2022-08-05 14:06:12 +02:00
parent b126ab4dec
commit 73383cc466
625 changed files with 52358 additions and 11660 deletions
@@ -1,4 +1,3 @@
-import { Type } from "class-transformer"
 import {
  IsArray,
  IsBoolean,
@@ -11,16 +10,19 @@ import {
  IsString,
  ValidateNested,
 } from "class-validator"
-import { transformIdableFields } from "medusa-core-utils"
 import {
  defaultAdminDraftOrdersFields,
  defaultAdminDraftOrdersRelations,
 } from "."
+
+import { AddressPayload } from "../../../../types/common"
 import { DraftOrder } from "../../../.."
 import { DraftOrderService } from "../../../../services"
-import { AddressPayload } from "../../../../types/common"
-import { validator } from "../../../../utils/validator"
 import { EntityManager } from "typeorm"
+import { Type } from "class-transformer"
+import { transformIdableFields } from "medusa-core-utils"
+import { validator } from "../../../../utils/validator"
+
 /**
 * @oas [post] /draft-orders
 * operationId: "PostDraftOrders"
@@ -40,24 +42,27 @@ import { EntityManager } from "typeorm"
 *           status:
 *             description: "The status of the draft order"
 *             type: string
+ *             enum: [open, completed]
 *           email:
 *             description: "The email of the customer of the draft order"
 *             type: string
+ *             format: email
 *           billing_address:
 *             description: "The Address to be used for billing purposes."
- *             anyOf:
- *               - $ref: "#/components/schemas/address"
+ *             $ref: "#/components/schemas/address"
 *           shipping_address:
 *             description: "The Address to be used for shipping."
- *             anyOf:
- *               - $ref: "#/components/schemas/address"
+ *             $ref: "#/components/schemas/address"
 *           items:
 *             description: The Line Items that have been received.
 *             type: array
 *             items:
+ *               type: object
+ *               required:
+ *                 - quantity
 *               properties:
 *                 variant_id:
- *                   description: The id of the Product Variant to generate the Line Item from.
+ *                   description: The ID of the Product Variant to generate the Line Item from.
 *                   type: string
 *                 unit_price:
 *                   description: The potential custom price of the item.
@@ -72,18 +77,21 @@ import { EntityManager } from "typeorm"
 *                   description: The optional key-value map with additional details about the Line Item.
 *                   type: object
 *           region_id:
- *             description: The id of the region for the draft order
+ *             description: The ID of the region for the draft order
 *             type: string
 *           discounts:
 *             description: The discounts to add on the draft order
 *             type: array
 *             items:
+ *               type: object
+ *               required:
+ *                 - code
 *               properties:
 *                 code:
 *                   description: The code of the discount to apply
 *                   type: string
 *           customer_id:
- *             description: The id of the customer to add on the draft order
+ *             description: The ID of the customer to add on the draft order
 *             type: string
 *           no_notification_order:
 *             description: An optional flag passed to the resulting order to determine use of notifications.
@@ -92,9 +100,12 @@ import { EntityManager } from "typeorm"
 *             description: The shipping methods for the draft order
 *             type: array
 *             items:
+ *               type: object
+ *               required:
+ *                  - option_id
 *               properties:
 *                 option_id:
- *                   description: The id of the shipping option in use
+ *                   description: The ID of the shipping option in use
 *                   type: string
 *                 data:
 *                   description: The optional additional data needed for the shipping method
@@ -1,3 +1,8 @@
+import {
+  CartService,
+  DraftOrderService,
+  LineItemService,
+} from "../../../../services"
 import {
  IsBoolean,
  IsInt,
@@ -5,35 +10,34 @@ import {
  IsOptional,
  IsString,
 } from "class-validator"
-import { MedusaError } from "medusa-core-utils"
-import { EntityManager } from "typeorm"
 import {
  defaultAdminDraftOrdersCartFields,
  defaultAdminDraftOrdersCartRelations,
  defaultAdminDraftOrdersFields,
 } from "."
-import {
-  CartService,
-  DraftOrderService,
-  LineItemService,
-} from "../../../../services"
-import { validator } from "../../../../utils/validator"
+
+import { EntityManager } from "typeorm"
 import { FlagRouter } from "../../../../utils/flag-router"
+import { MedusaError } from "medusa-core-utils"
+import { validator } from "../../../../utils/validator"
+
 /**
 * @oas [post] /draft-orders/{id}/line-items
 * operationId: "PostDraftOrdersDraftOrderLineItems"
 * summary: "Create a Line Item for Draft Order"
 * description: "Creates a Line Item for the Draft Order"
 * x-authenticated: true
+ * parameters:
+ *   - (path) id=* {string} The ID of the Draft Order.
 * requestBody:
 *   content:
 *     application/json:
- *       required:
- *         - quantity
 *       schema:
+ *         required:
+ *           - quantity
 *         properties:
 *           variant_id:
- *             description: The id of the Product Variant to generate the Line Item from.
+ *             description: The ID of the Product Variant to generate the Line Item from.
 *             type: string
 *           unit_price:
 *             description: The potential custom price of the item.
@@ -41,6 +45,7 @@ import { FlagRouter } from "../../../../utils/flag-router"
 *           title:
 *             description: The potential custom title of the item.
 *             type: string
+ *             default: "Custom item"
 *           quantity:
 *             description: The quantity of the Line Item.
 *             type: integer
@@ -7,7 +7,7 @@ import { EntityManager } from "typeorm"
 * description: "Deletes a Draft Order"
 * x-authenticated: true
 * parameters:
- *   - (path) id=* {string} The id of the Draft Order.
+ *   - (path) id=* {string} The ID of the Draft Order.
 * tags:
 *   - Draft Order
 * responses:
@@ -19,12 +19,15 @@ import { EntityManager } from "typeorm"
 *           properties:
 *             id:
 *               type: string
- *               description: The id of the deleted Draft Order.
+ *               description: The ID of the deleted Draft Order.
 *             object:
 *               type: string
 *               description: The type of the object that was deleted.
+ *               default: draft-order
 *             deleted:
 *               type: boolean
+ *               description: Whether the draft order was deleted successfully or not.
+ *               default: true
 */
 export default async (req, res) => {
  const { id } = req.params
@@ -1,12 +1,14 @@
-import { MedusaError } from "medusa-core-utils"
-import { EntityManager } from "typeorm"
+import { CartService, DraftOrderService } from "../../../../services"
 import {
  defaultAdminDraftOrdersCartFields,
  defaultAdminDraftOrdersCartRelations,
  defaultAdminDraftOrdersFields,
 } from "."
+
 import { DraftOrder } from "../../../.."
-import { CartService, DraftOrderService } from "../../../../services"
+import { EntityManager } from "typeorm"
+import { MedusaError } from "medusa-core-utils"
+
 /**
 * @oas [delete] /draft-orders/{id}/line-items/{line_id}
 * operationId: DeleteDraftOrdersDraftOrderLineItemsItem
@@ -14,8 +16,8 @@ import { CartService, DraftOrderService } from "../../../../services"
 * description: "Removes a Line Item from a Draft Order."
 * x-authenticated: true
 * parameters:
- *   - (path) id=* {string} The id of the Draft Order.
- *   - (path) line_id=* {string} The id of the Draft Order.
+ *   - (path) id=* {string} The ID of the Draft Order.
+ *   - (path) line_id=* {string} The ID of the Draft Order.
 * tags:
 *   - Draft Order
 * responses:
@@ -1,11 +1,12 @@
-import {
-  defaultAdminDraftOrdersRelations,
-  defaultAdminDraftOrdersFields,
-  defaultAdminDraftOrdersCartRelations,
-  defaultAdminDraftOrdersCartFields,
-} from "."
-import { DraftOrder } from "../../../.."
 import { CartService, DraftOrderService } from "../../../../services"
+import {
+  defaultAdminDraftOrdersCartFields,
+  defaultAdminDraftOrdersCartRelations,
+  defaultAdminDraftOrdersFields,
+  defaultAdminDraftOrdersRelations,
+} from "."
+
+import { DraftOrder } from "../../../.."

 /**
 * @oas [get] /draft-orders/{id}
@@ -14,7 +15,7 @@ import { CartService, DraftOrderService } from "../../../../services"
 * description: "Retrieves a Draft Order."
 * x-authenticated: true
 * parameters:
- *   - (path) id=* {string} The id of the Draft Order.
+ *   - (path) id=* {string} The ID of the Draft Order.
 * tags:
 *   - Draft Order
 * responses:
@@ -1,20 +1,26 @@
+import { IsNumber, IsOptional, IsString } from "class-validator"
 import {
  defaultAdminDraftOrdersFields,
  defaultAdminDraftOrdersRelations,
 } from "."
-import { DraftOrderService } from "../../../../services"
-import { IsNumber, IsOptional, IsString } from "class-validator"
-import { validator } from "../../../../utils/validator"
-import { Type } from "class-transformer"
-import { DraftOrderListSelector } from "../../../../types/draft-orders"
-import { FindConfig } from "../../../../types/common"
+
 import { DraftOrder } from "../../../../models"
+import { DraftOrderListSelector } from "../../../../types/draft-orders"
+import { DraftOrderService } from "../../../../services"
+import { FindConfig } from "../../../../types/common"
+import { Type } from "class-transformer"
+import { validator } from "../../../../utils/validator"
+
 /**
 * @oas [get] /draft-orders
 * operationId: "GetDraftOrders"
 * summary: "List Draft Orders"
 * description: "Retrieves an list of Draft Orders"
 * x-authenticated: true
+ * parameters:
+ *   - (query) offset=0 {number} The number of items to skip before the results.
+ *   - (query) limit=50 {number} Limit the number of items returned.
+ *   - (query) q {string} a search term to search emails in carts associated with draft orders and display IDs of draft orders
 * tags:
 *   - Draft Order
 * responses:
@@ -24,8 +30,19 @@ import { DraftOrder } from "../../../../models"
 *       application/json:
 *         schema:
 *           properties:
- *             draft_order:
- *               $ref: "#/components/schemas/draft-order"
+ *             draft_orders:
+ *               type: array
+ *               items:
+ *                 $ref: "#/components/schemas/draft-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 default async (req, res) => {
@@ -1,4 +1,3 @@
-import { EntityManager } from "typeorm"
 import {
  CartService,
  DraftOrderService,
@@ -10,8 +9,10 @@ import {
  defaultAdminOrdersRelations as defaultOrderRelations,
 } from "../orders/index"

+import { EntityManager } from "typeorm"
+
 /**
- * @oas [post] /draft-orders/{id}/register-payment
+ * @oas [post] /draft-orders/{id}/pay
 * summary: "Registers a payment for a Draft Order"
 * operationId: "PostDraftOrdersDraftOrderRegisterPayment"
 * description: "Registers a payment for a Draft Order."
@@ -27,7 +28,7 @@ import {
 *       application/json:
 *         schema:
 *           properties:
- *             draft_order:
+ *             order:
 *               $ref: "#/components/schemas/draft-order"
 */

@@ -1,8 +1,4 @@
-import { MedusaError } from "medusa-core-utils"
-import {
-  defaultAdminDraftOrdersCartFields,
-  defaultAdminDraftOrdersCartRelations,
-} from "."
+import { CartService, DraftOrderService } from "../../../../services"
 import {
  IsArray,
  IsBoolean,
@@ -11,12 +7,17 @@ import {
  IsString,
  ValidateNested,
 } from "class-validator"
-import { CartService, DraftOrderService } from "../../../../services"
-import { Type } from "class-transformer"
+import {
+  defaultAdminDraftOrdersCartFields,
+  defaultAdminDraftOrdersCartRelations,
+} from "."
+
 import { AddressPayload } from "../../../../types/common"
-import { validator } from "../../../../utils/validator"
-import { EntityManager } from "typeorm"
 import { DraftOrderStatus } from "../../../../models"
+import { EntityManager } from "typeorm"
+import { MedusaError } from "medusa-core-utils"
+import { Type } from "class-transformer"
+import { validator } from "../../../../utils/validator"

 /**
 * @oas [post] /admin/draft-orders/{id}
@@ -25,7 +26,7 @@ import { DraftOrderStatus } from "../../../../models"
 * description: "Updates a Draft Order."
 * x-authenticated: true
 * parameters:
- *   - (path) id=* {string} The id of the Draft Order.
+ *   - (path) id=* {string} The ID of the Draft Order.
 * requestBody:
 *   content:
 *     application/json:
@@ -33,22 +34,30 @@ import { DraftOrderStatus } from "../../../../models"
 *         properties:
 *           region_id:
 *             type: string
- *             description: The id of the Region to create the Draft Order in.
+ *             description: The ID of the Region to create the Draft Order in.
+ *           country_code:
+ *             type: string
+ *             description: "The 2 character ISO code for the Country."
+ *             externalDocs:
+ *                url: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
+ *                description: See a list of codes.
 *           email:
 *             type: string
 *             description: "An email to be used on the Draft Order."
+ *             format: email
 *           billing_address:
 *             description: "The Address to be used for billing purposes."
- *             anyOf:
- *               - $ref: "#/components/schemas/address"
+ *             $ref: "#/components/schemas/address"
 *           shipping_address:
 *             description: "The Address to be used for shipping."
- *             anyOf:
- *               - $ref: "#/components/schemas/address"
+ *             $ref: "#/components/schemas/address"
 *           discounts:
 *             description: "An array of Discount codes to add to the Draft Order."
 *             type: array
 *             items:
+ *               type: object
+ *               required:
+ *                 - code
 *               properties:
 *                 code:
 *                   description: "The code that a Discount is identifed by."
@@ -57,7 +66,7 @@ import { DraftOrderStatus } from "../../../../models"
 *             description: "An optional flag passed to the resulting order to determine use of notifications."
 *             type: boolean
 *           customer_id:
- *             description: "The id of the Customer to associate the Draft Order with."
+ *             description: "The ID of the Customer to associate the Draft Order with."
 *             type: string
 * tags:
 *   - Draft Order
@@ -1,21 +1,26 @@
+import { CartService, DraftOrderService } from "../../../../services"
 import { IsInt, IsObject, IsOptional, IsString } from "class-validator"
-import { MedusaError } from "medusa-core-utils"
-import { EntityManager } from "typeorm"
 import {
  defaultAdminDraftOrdersCartFields,
  defaultAdminDraftOrdersCartRelations,
  defaultAdminDraftOrdersFields,
 } from "."
+
 import { DraftOrder } from "../../../.."
+import { EntityManager } from "typeorm"
 import { LineItemUpdate } from "../../../../types/cart"
-import { CartService, DraftOrderService } from "../../../../services"
+import { MedusaError } from "medusa-core-utils"
 import { validator } from "../../../../utils/validator"
+
 /**
 * @oas [post] /draft-orders/{id}/line-items/{line_id}
 * operationId: "PostDraftOrdersDraftOrderLineItemsItem"
 * summary: "Update a Line Item for a Draft Order"
 * description: "Updates a Line Item for a Draft Order"
 * x-authenticated: true
+ * parameters:
+ *   - (path) id=* {string} The ID of the Draft Order.
+ *   - (path) line_id=* {string} The ID of the Line Item.
 * requestBody:
 *   content:
 *     application/json: