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

packages/medusa/src/models/shipping-method.ts

@@ -10,15 +10,15 @@ import {
   OneToOne,
   PrimaryColumn,
 } from "typeorm"
-import { DbAwareColumn } from "../utils/db-aware-column"
 
-import { ClaimOrder } from "./claim-order"
-import { Order } from "./order"
 import { Cart } from "./cart"
-import { Swap } from "./swap"
+import { ClaimOrder } from "./claim-order"
+import { DbAwareColumn } from "../utils/db-aware-column"
+import { Order } from "./order"
 import { Return } from "./return"
-import { ShippingOption } from "./shipping-option"
 import { ShippingMethodTaxLine } from "./shipping-method-tax-line"
+import { ShippingOption } from "./shipping-option"
+import { Swap } from "./swap"
 import { generateEntityId } from "../utils/generate-entity-id"
 
 @Check(
@@ -100,36 +100,67 @@ export class ShippingMethod {
  * title: "Shipping Method"
  * description: "Shipping Methods represent a way in which an Order or Return can be shipped. Shipping Methods are built from a Shipping Option, but may contain additional details, that can be necessary for the Fulfillment Provider to handle the shipment."
  * x-resourceId: shipping_method
+ * required:
+ *   - shipping_option_id
+ *   - price
  * properties:
  *   id:
- *     description: "The id of the Shipping Method. This value will be prefixed with `sm_`."
  *     type: string
+ *     description: The shipping method's ID
+ *     example: sm_01F0YET7DR2E7CYVSDHM593QG2
  *   shipping_option_id:
  *     description: "The id of the Shipping Option that the Shipping Method is built from."
  *     type: string
+ *     example: so_01G1G5V27GYX4QXNARRQCW1N8T
  *   shipping_option:
- *     description: "The Shipping Option that the Shipping Method is built from."
- *     anyOf:
- *       - $ref: "#/components/schemas/shipping_option"
+ *     description: Available if the relation `shipping_option` is expanded.
+ *     $ref: "#/components/schemas/shipping_option"
  *   order_id:
  *     description: "The id of the Order that the Shipping Method is used on."
  *     type: string
+ *     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
+ *   order:
+ *     description: An order object. Available if the relation `order` is expanded.
+ *     type: object
  *   return_id:
  *     description: "The id of the Return that the Shipping Method is used on."
  *     type: string
+ *     example: null
+ *   return_order:
+ *     description: A return object. Available if the relation `return_order` is expanded.
+ *     type: object
  *   swap_id:
  *     description: "The id of the Swap that the Shipping Method is used on."
  *     type: string
+ *     example: null
+ *   swap:
+ *     description: A swap object. Available if the relation `swap` is expanded.
+ *     type: object
  *   cart_id:
  *     description: "The id of the Cart that the Shipping Method is used on."
  *     type: string
+ *     example: cart_01G8ZH853Y6TFXWPG5EYE81X63
+ *   cart:
+ *     description: A cart object. Available if the relation `cart` is expanded.
+ *     type: object
  *   claim_order_id:
  *     description: "The id of the Claim that the Shipping Method is used on."
  *     type: string
+ *     example: null
+ *   claim_order:
+ *     description: A claim order object. Available if the relation `claim_order` is expanded.
+ *     type: object
+ *   tax_lines:
+ *     type: array
+ *     description: Available if the relation `tax_lines` is expanded.
+ *     items:
+ *       $ref: "#/components/schemas/tax_line"
  *   price:
  *     description: "The amount to charge for the Shipping Method. The currency of the price is defined by the Region that the Order that the Shipping Method belongs to is a part of."
  *     type: integer
+ *     example: 200
  *   data:
  *     description: "Additional data that the Fulfillment Provider needs to fulfill the shipment. This is used in combination with the Shipping Options data, and may contain information such as a drop point id."
  *     type: object
+ *     example: {}
  */