From cac13a88da42fa986bd7352fbc12a318b566d98f Mon Sep 17 00:00:00 2001
From: Patrick <116003638+patrick-medusajs@users.noreply.github.com>
Date: Mon, 13 Feb 2023 11:59:36 -0500
Subject: [PATCH] feat(oas) - accurate model OAS representation - R to U
 (#3250)

### Scope

Models R to U

### What

Refactor OAS for models to accurately represent their shape in API responses.

### Why

About 33% of model fields are not accurately represented in the OAS. Most of the issues are:
- fields that can not be omitted in the response are not declared as `required`
- fields that could return `null` as their value are not declared as `nullable: true`

When using a code generator, these OAS issues would lead to inaccurate response shapes in the generated client.

### How

#### nullable
Fields meeting at least one of the following condition will be represented as `nullable: true` in OAS:
* The field is decorated with `@Column({ nullable: true })`
* The field is decorated with `@OneToOne`, `@ManyToOne`
* The field is decorated with `@DeleteDateColumn`

#### optional
Fields meeting at least one of the following conditions will never be listed as `required` in OAS and will be considered optional and could be omitted in the response:
* The field is decorated with `@OneToOne`, `@ManyToOne`, `@OneToMany`, `@ManyToMany`
* The field is decorated with `@FeatureFlagColumn`
* The field is decorated with `@Column({select: false})`
* The field is representing dynamic values not persisted in the database

Fields not meeting any of the conditions above will be declared as `required` and are expected to be present in the response.

### Test
* Ran OAS validator.
* Ran docs build script.

Expect OAS changes to be reflected in the API documentation.
---
 .changeset/spicy-vans-shave.md                |  5 +
 packages/medusa/src/models/refund.ts          | 49 ++++++---
 packages/medusa/src/models/region.ts          | 40 +++++---
 packages/medusa/src/models/return-item.ts     | 41 +++++---
 packages/medusa/src/models/return-reason.ts   | 44 ++++++---
 packages/medusa/src/models/return.ts          | 76 +++++++++-----
 .../src/models/sales-channel-location.ts      | 23 ++++-
 packages/medusa/src/models/sales-channel.ts   | 22 +++--
 .../src/models/shipping-method-tax-line.ts    | 38 ++++---
 packages/medusa/src/models/shipping-method.ts | 99 ++++++++++++-------
 .../src/models/shipping-option-requirement.ts | 16 +--
 packages/medusa/src/models/shipping-option.ts | 52 +++++++---
 .../medusa/src/models/shipping-profile.ts     | 24 +++--
 .../medusa/src/models/shipping-tax-rate.ts    | 18 ++--
 packages/medusa/src/models/staged-job.ts      | 11 ++-
 packages/medusa/src/models/store.ts           | 49 +++++++--
 packages/medusa/src/models/swap.ts            | 84 ++++++++++------
 packages/medusa/src/models/tax-line.ts        | 23 +++--
 packages/medusa/src/models/tax-provider.ts    |  7 +-
 packages/medusa/src/models/tax-rate.ts        | 57 ++++++-----
 packages/medusa/src/models/tracking-link.ts   | 32 ++++--
 packages/medusa/src/models/user.ts            | 38 +++++--
 22 files changed, 579 insertions(+), 269 deletions(-)
 create mode 100644 .changeset/spicy-vans-shave.md

diff --git a/.changeset/spicy-vans-shave.md b/.changeset/spicy-vans-shave.md
new file mode 100644
index 0000000000..54a4d29e98
--- /dev/null
+++ b/.changeset/spicy-vans-shave.md
@@ -0,0 +1,5 @@
+---
+"@medusajs/medusa": patch
+---
+
+feat(oas) - accurate model OAS representation - R to U
diff --git a/packages/medusa/src/models/refund.ts b/packages/medusa/src/models/refund.ts
index 6b0640a30a..81ec8e55a0 100644
--- a/packages/medusa/src/models/refund.ts
+++ b/packages/medusa/src/models/refund.ts
@@ -67,27 +67,50 @@ export class Refund extends BaseEntity {
  * description: "Refund represent an amount of money transfered back to the Customer for a given reason. Refunds may occur in relation to Returns, Swaps and Claims, but can also be initiated by a store operator."
  * type: object
  * required:
- *   - order_id
  *   - amount
+ *   - created_at
+ *   - id
+ *   - idempotency_key
+ *   - metadata
+ *   - note
+ *   - order_id
+ *   - payment_id
+ *   - reason
+ *   - updated_at
  * properties:
  *   id:
- *     type: string
  *     description: The refund's ID
+ *     type: string
  *     example: ref_01G1G5V27GYX4QXNARRQCW1N8T
  *   order_id:
- *     description: "The id of the Order that the Refund is related to."
+ *     description: The id of the Order that the Refund is related to.
+ *     nullable: true
  *     type: string
  *     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
+ *   order:
+ *     description: An order object. Available if the relation `order` is expanded.
+ *     nullable: true
+ *     $ref: "#/components/schemas/Order"
+ *   payment_id:
+ *     description: The payment's ID if available
+ *     nullable: true
+ *     type: string
+ *     example: pay_01G8ZCC5W42ZNY842124G7P5R9
+ *   payment:
+ *     description: Available if the relation `payment` is expanded.
+ *     nullable: true
+ *     $ref: "#/components/schemas/Payment"
  *   amount:
- *     description: "The amount that has be refunded to the Customer."
+ *     description: The amount that has be refunded to the Customer.
  *     type: integer
  *     example: 1000
  *   note:
- *     description: "An optional note explaining why the amount was refunded."
+ *     description: An optional note explaining why the amount was refunded.
+ *     nullable: true
  *     type: string
  *     example: I didn't like it
  *   reason:
- *     description: "The reason given for the Refund, will automatically be set when processed as part of a Swap, Claim or Return."
+ *     description: The reason given for the Refund, will automatically be set when processed as part of a Swap, Claim or Return.
  *     type: string
  *     enum:
  *       - discount
@@ -97,25 +120,23 @@ export class Refund extends BaseEntity {
  *       - other
  *     example: return
  *   idempotency_key:
- *     type: string
  *     description: Randomly generated key used to continue the completion of the refund in case of failure.
+ *     nullable: true
+ *     type: string
  *     externalDocs:
  *       url: https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key
  *       description: Learn more how to use the idempotency key.
  *   created_at:
+ *     description: The date with timezone at which the resource was created.
  *     type: string
- *     description: "The date with timezone at which the resource was created."
  *     format: date-time
  *   updated_at:
+ *     description: The date with timezone at which the resource was updated.
  *     type: string
- *     description: "The date with timezone at which the resource was updated."
- *     format: date-time
- *   deleted_at:
- *     type: string
- *     description: "The date with timezone at which the resource was deleted."
  *     format: date-time
  *   metadata:
- *     type: object
  *     description: An optional key-value map with additional details
+ *     nullable: true
+ *     type: object
  *     example: {car: "white"}
  */
diff --git a/packages/medusa/src/models/region.ts b/packages/medusa/src/models/region.ts
index 033451155a..90ff7daae6 100644
--- a/packages/medusa/src/models/region.ts
+++ b/packages/medusa/src/models/region.ts
@@ -112,20 +112,29 @@ export class Region extends SoftDeletableEntity {
  * description: "Regions hold settings for how Customers in a given geographical location shop. The is, for example, where currencies and tax rates are defined. A Region can consist of multiple countries to accomodate common shopping settings across countries."
  * type: object
  * required:
- *   - name
+ *   - automatic_taxes
+ *   - created_at
  *   - currency_code
+ *   - deleted_at
+ *   - gift_cards_taxable
+ *   - id
+ *   - metadata
+ *   - name
+ *   - tax_code
+ *   - tax_provider_id
  *   - tax_rate
+ *   - updated_at
  * properties:
  *   id:
- *     type: string
  *     description: The region's ID
+ *     type: string
  *     example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
  *   name:
- *     description: "The name of the region as displayed to the customer. If the Region only has one country it is recommended to write the country name."
+ *     description: The name of the region as displayed to the customer. If the Region only has one country it is recommended to write the country name.
  *     type: string
  *     example: EU
  *   currency_code:
- *     description: "The 3 character currency code that the Region uses."
+ *     description: The 3 character currency code that the Region uses.
  *     type: string
  *     example: usd
  *     externalDocs:
@@ -133,9 +142,10 @@ export class Region extends SoftDeletableEntity {
  *       description: See a list of codes.
  *   currency:
  *     description: Available if the relation `currency` is expanded.
+ *     nullable: true
  *     $ref: "#/components/schemas/Currency"
  *   tax_rate:
- *     description: "The tax rate that should be charged on purchases in the Region."
+ *     description: The tax rate that should be charged on purchases in the Region.
  *     type: number
  *     example: 0
  *   tax_rates:
@@ -144,7 +154,8 @@ export class Region extends SoftDeletableEntity {
  *     items:
  *       $ref: "#/components/schemas/TaxRate"
  *   tax_code:
- *     description: "The tax code used on purchases in the Region. This may be used by other systems for accounting purposes."
+ *     description: The tax code used on purchases in the Region. This may be used by other systems for accounting purposes.
+ *     nullable: true
  *     type: string
  *     example: null
  *   gift_cards_taxable:
@@ -161,11 +172,13 @@ export class Region extends SoftDeletableEntity {
  *     items:
  *       $ref: "#/components/schemas/Country"
  *   tax_provider_id:
- *     type: string
  *     description: The ID of the tax provider used in this region
+ *     nullable: true
+ *     type: string
  *     example: null
  *   tax_provider:
  *     description: Available if the relation `tax_provider` is expanded.
+ *     nullable: true
  *     $ref: "#/components/schemas/TaxProvider"
  *   payment_providers:
  *     description: The Payment Providers that can be used to process Payments in the Region. Available if the relation `payment_providers` is expanded.
@@ -173,27 +186,30 @@ export class Region extends SoftDeletableEntity {
  *     items:
  *       $ref: "#/components/schemas/PaymentProvider"
  *   fulfillment_providers:
- *     description: The Fulfillment Providers that can be used to fulfill orders in the Region. Available if the relation `payment_providers` is expanded.
+ *     description: The Fulfillment Providers that can be used to fulfill orders in the Region. Available if the relation `fulfillment_providers` is expanded.
  *     type: array
  *     items:
  *       $ref: "#/components/schemas/FulfillmentProvider"
  *   includes_tax:
  *     description: "[EXPERIMENTAL] Does the prices for the region include tax"
  *     type: boolean
+ *     default: false
  *   created_at:
+ *     description: The date with timezone at which the resource was created.
  *     type: string
- *     description: "The date with timezone at which the resource was created."
  *     format: date-time
  *   updated_at:
+ *     description: The date with timezone at which the resource was updated.
  *     type: string
- *     description: "The date with timezone at which the resource was updated."
  *     format: date-time
  *   deleted_at:
+ *     description: The date with timezone at which the resource was deleted.
+ *     nullable: true
  *     type: string
- *     description: "The date with timezone at which the resource was deleted."
  *     format: date-time
  *   metadata:
- *     type: object
  *     description: An optional key-value map with additional details
+ *     nullable: true
+ *     type: object
  *     example: {car: "white"}
  */
diff --git a/packages/medusa/src/models/return-item.ts b/packages/medusa/src/models/return-item.ts
index a1a5cf9020..b746c3f9fa 100644
--- a/packages/medusa/src/models/return-item.ts
+++ b/packages/medusa/src/models/return-item.ts
@@ -53,52 +53,67 @@ export class ReturnItem {
  * description: "Correlates a Line Item with a Return, keeping track of the quantity of the Line Item that will be returned."
  * type: object
  * required:
- *   - return_id
+ *   - is_requested
  *   - item_id
+ *   - metadata
+ *   - note
+ *   - quantity
+ *   - reason_id
+ *   - received_quantity
+ *   - requested_quantity
+ *   - return_id
  * properties:
  *   return_id:
- *     description: "The id of the Return that the Return Item belongs to."
+ *     description: The id of the Return that the Return Item belongs to.
  *     type: string
  *     example: ret_01F0YET7XPCMF8RZ0Y151NZV2V
- *   return_order:
- *     description: Available if the relation `return_order` is expanded.
- *     $ref: "#/components/schemas/Return"
  *   item_id:
- *     description: "The id of the Line Item that the Return Item references."
+ *     description: The id of the Line Item that the Return Item references.
  *     type: string
  *     example: item_01G8ZC9GWT6B2GP5FSXRXNFNGN
+ *   return_order:
+ *     description: Available if the relation `return_order` is expanded.
+ *     nullable: true
+ *     $ref: "#/components/schemas/Return"
  *   item:
  *     description: Available if the relation `item` is expanded.
+ *     nullable: true
  *     $ref: "#/components/schemas/LineItem"
  *   quantity:
- *     description: "The quantity of the Line Item that is included in the Return."
+ *     description: The quantity of the Line Item that is included in the Return.
  *     type: integer
  *     example: 1
  *   is_requested:
- *     description: "Whether the Return Item was requested initially or received unexpectedly in the warehouse."
+ *     description: Whether the Return Item was requested initially or received unexpectedly in the warehouse.
  *     type: boolean
  *     default: true
  *   requested_quantity:
- *     description: "The quantity that was originally requested to be returned."
+ *     description: The quantity that was originally requested to be returned.
+ *     nullable: true
  *     type: integer
  *     example: 1
- *   recieved_quantity:
- *     description: "The quantity that was received in the warehouse."
+ *   received_quantity:
+ *     description: The quantity that was received in the warehouse.
+ *     nullable: true
  *     type: integer
  *     example: 1
  *   reason_id:
  *     description: The ID of the reason for returning the item.
+ *     nullable: true
  *     type: string
  *     example: rr_01G8X82GCCV2KSQHDBHSSAH5TQ
  *   reason:
  *     description: Available if the relation `reason` is expanded.
+ *     nullable: true
  *     $ref: "#/components/schemas/ReturnReason"
  *   note:
- *     description: "An optional note with additional details about the Return."
+ *     description: An optional note with additional details about the Return.
+ *     nullable: true
  *     type: string
  *     example: I didn't like it.
  *   metadata:
- *     type: object
  *     description: An optional key-value map with additional details
+ *     nullable: true
+ *     type: object
  *     example: {car: "white"}
  */
diff --git a/packages/medusa/src/models/return-reason.ts b/packages/medusa/src/models/return-reason.ts
index eeca6b66ed..f303ce4145 100644
--- a/packages/medusa/src/models/return-reason.ts
+++ b/packages/medusa/src/models/return-reason.ts
@@ -53,49 +53,61 @@ export class ReturnReason extends SoftDeletableEntity {
  * description: "A Reason for why a given product is returned. A Return Reason can be used on Return Items in order to indicate why a Line Item was returned."
  * type: object
  * required:
- *   - value
+ *   - created_at
+ *   - deleted_at
+ *   - description
+ *   - id
  *   - label
+ *   - metadata
+ *   - parent_return_reason_id
+ *   - updated_at
+ *   - value
  * properties:
  *   id:
+ *     description: The return reason's ID
  *     type: string
- *     description: The cart's ID
  *     example: rr_01G8X82GCCV2KSQHDBHSSAH5TQ
- *   description:
- *     description: "A description of the Reason."
- *     type: string
- *     example: Items that are damaged
- *   label:
- *     description: "A text that can be displayed to the Customer as a reason."
- *     type: string
- *     example: Damaged goods
  *   value:
- *     description: "The value to identify the reason by."
+ *     description: The value to identify the reason by.
  *     type: string
  *     example: damaged
- *   parent_return_reason_id:
+ *   label:
+ *     description: A text that can be displayed to the Customer as a reason.
  *     type: string
+ *     example: Damaged goods
+ *   description:
+ *     description: A description of the Reason.
+ *     nullable: true
+ *     type: string
+ *     example: Items that are damaged
+ *   parent_return_reason_id:
  *     description: The ID of the parent reason.
+ *     nullable: true
+ *     type: string
  *     example: null
  *   parent_return_reason:
  *     description: Available if the relation `parent_return_reason` is expanded.
+ *     nullable: true
  *     $ref: "#/components/schemas/ReturnReason"
  *   return_reason_children:
  *     description: Available if the relation `return_reason_children` is expanded.
  *     $ref: "#/components/schemas/ReturnReason"
  *   created_at:
+ *     description: The date with timezone at which the resource was created.
  *     type: string
- *     description: "The date with timezone at which the resource was created."
  *     format: date-time
  *   updated_at:
+ *     description: The date with timezone at which the resource was updated.
  *     type: string
- *     description: "The date with timezone at which the resource was updated."
  *     format: date-time
  *   deleted_at:
+ *     description: The date with timezone at which the resource was deleted.
+ *     nullable: true
  *     type: string
- *     description: "The date with timezone at which the resource was deleted."
  *     format: date-time
  *   metadata:
- *     type: object
  *     description: An optional key-value map with additional details
+ *     nullable: true
+ *     type: object
  *     example: {car: "white"}
  */
diff --git a/packages/medusa/src/models/return.ts b/packages/medusa/src/models/return.ts
index b2a9c53544..5b5f6558cc 100644
--- a/packages/medusa/src/models/return.ts
+++ b/packages/medusa/src/models/return.ts
@@ -103,14 +103,27 @@ export class Return extends BaseEntity {
  * description: "Return orders hold information about Line Items that a Customer wishes to send back, along with how the items will be returned. Returns can be used as part of a Swap."
  * type: object
  * required:
+ *   - claim_order_id
+ *   - created_at
+ *   - id
+ *   - idempotency_key
+ *   - location_id
+ *   - metadata
+ *   - no_notification
+ *   - order_id
+ *   - received_at
  *   - refund_amount
+ *   - shipping_data
+ *   - status
+ *   - swap_id
+ *   - updated_at
  * properties:
  *   id:
- *     type: string
  *     description: The return's ID
+ *     type: string
  *     example: ret_01F0YET7XPCMF8RZ0Y151NZV2V
  *   status:
- *     description: "Status of the Return."
+ *     description: Status of the Return.
  *     type: string
  *     enum:
  *       - requested
@@ -124,63 +137,78 @@ export class Return extends BaseEntity {
  *     items:
  *       $ref: "#/components/schemas/ReturnItem"
  *   swap_id:
- *     description: "The ID of the Swap that the Return is a part of."
+ *     description: The ID of the Swap that the Return is a part of.
+ *     nullable: true
  *     type: string
  *     example: null
  *   swap:
  *     description: A swap object. Available if the relation `swap` is expanded.
- *     type: object
- *   order_id:
- *     description: "The ID of the Order that the Return is made from."
- *     type: string
- *     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
- *   order:
- *     description: An order object. Available if the relation `order` is expanded.
- *     type: object
+ *     nullable: true
+ *     $ref: "#/components/schemas/Swap"
  *   claim_order_id:
- *     description: "The ID of the Claim that the Return is a part of."
+ *     description: The ID of the Claim that the Return is a part of.
+ *     nullable: true
  *     type: string
  *     example: null
  *   claim_order:
  *     description: A claim order object. Available if the relation `claim_order` is expanded.
- *     type: object
+ *     nullable: true
+ *     $ref: "#/components/schemas/ClaimOrder"
+ *   order_id:
+ *     description: The ID of the Order that the Return is made from.
+ *     nullable: true
+ *     type: string
+ *     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
+ *   order:
+ *     description: An order object. Available if the relation `order` is expanded.
+ *     nullable: true
+ *     $ref: "#/components/schemas/Order"
  *   shipping_method:
  *     description: The Shipping Method that will be used to send the Return back. Can be null if the Customer facilitates the return shipment themselves. Available if the relation `shipping_method` is expanded.
- *     type: array
- *     items:
- *       $ref: "#/components/schemas/ShippingMethod"
+ *     nullable: true
+ *     $ref: "#/components/schemas/ShippingMethod"
  *   shipping_data:
- *     description: "Data about the return shipment as provided by the Fulfilment Provider that handles the return shipment."
+ *     description: Data about the return shipment as provided by the Fulfilment Provider that handles the return shipment.
+ *     nullable: true
  *     type: object
  *     example: {}
+ *   location_id:
+ *     description: The id of the stock location the return will be added back.
+ *     nullable: true
+ *     type: string
+ *     example: sloc_01G8TJSYT9M6AVS5N4EMNFS1EK
  *   refund_amount:
- *     description: "The amount that should be refunded as a result of the return."
+ *     description: The amount that should be refunded as a result of the return.
  *     type: integer
  *     example: 1000
  *   no_notification:
- *     description: "When set to true, no notification will be sent related to this return."
+ *     description: When set to true, no notification will be sent related to this return.
+ *     nullable: true
  *     type: boolean
  *     example: false
  *   idempotency_key:
- *     type: string
  *     description: Randomly generated key used to continue the completion of the return in case of failure.
+ *     nullable: true
+ *     type: string
  *     externalDocs:
  *       url: https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key
  *       description: Learn more how to use the idempotency key.
  *   received_at:
- *     description: "The date with timezone at which the return was received."
+ *     description: The date with timezone at which the return was received.
+ *     nullable: true
  *     type: string
  *     format: date-time
  *   created_at:
+ *     description: The date with timezone at which the resource was created.
  *     type: string
- *     description: "The date with timezone at which the resource was created."
  *     format: date-time
  *   updated_at:
+ *     description: The date with timezone at which the resource was updated.
  *     type: string
- *     description: "The date with timezone at which the resource was updated."
  *     format: date-time
  *   metadata:
- *     type: object
  *     description: An optional key-value map with additional details
+ *     nullable: true
+ *     type: object
  *     example: {car: "white"}
  */
diff --git a/packages/medusa/src/models/sales-channel-location.ts b/packages/medusa/src/models/sales-channel-location.ts
index b866b9e044..81f9ecb035 100644
--- a/packages/medusa/src/models/sales-channel-location.ts
+++ b/packages/medusa/src/models/sales-channel-location.ts
@@ -1,4 +1,4 @@
-import { BeforeInsert, Index, Column, ManyToOne, JoinColumn } from "typeorm"
+import { BeforeInsert, Column, Index, JoinColumn, ManyToOne } from "typeorm"
 
 import { FeatureFlagEntity } from "../utils/feature-flag-decorators"
 import { SoftDeletableEntity } from "../interfaces"
@@ -30,27 +30,40 @@ export class SalesChannelLocation extends SoftDeletableEntity {
  * title: "Sales Channel Stock Location"
  * description: "Sales Channel Stock Location link sales channels with stock locations."
  * type: object
+ * required:
+ *   - created_at
+ *   - deleted_at
+ *   - id
+ *   - location_id
+ *   - sales_channel_id
+ *   - updated_at
  * properties:
  *   id:
- *     type: string
  *     description: The Sales Channel Stock Location's ID
+ *     type: string
  *     example: scloc_01G8X9A7ESKAJXG2H0E6F1MW7A
  *   sales_channel_id:
  *     description: "The id of the Sales Channel"
  *     type: string
+ *     example: sc_01G8X9A7ESKAJXG2H0E6F1MW7A
  *   location_id:
  *     description: "The id of the Location Stock."
  *     type: string
+ *   sales_channel:
+ *     description: The sales channel the location is associated with. Available if the relation `sales_channel` is expanded.
+ *     nullable: true
+ *     $ref: "#/components/schemas/SalesChannel"
  *   created_at:
- *     type: string
  *     description: "The date with timezone at which the resource was created."
+ *     type: string
  *     format: date-time
  *   updated_at:
- *     type: string
  *     description: "The date with timezone at which the resource was updated."
+ *     type: string
  *     format: date-time
  *   deleted_at:
- *     type: string
  *     description: "The date with timezone at which the resource was deleted."
+ *     nullable: true
+ *     type: string
  *     format: date-time
  */
diff --git a/packages/medusa/src/models/sales-channel.ts b/packages/medusa/src/models/sales-channel.ts
index 1b05f84a7c..d72cab21a7 100644
--- a/packages/medusa/src/models/sales-channel.ts
+++ b/packages/medusa/src/models/sales-channel.ts
@@ -37,22 +37,29 @@ export class SalesChannel extends SoftDeletableEntity {
  * description: "A Sales Channel"
  * type: object
  * required:
+ *   - created_at
+ *   - deleted_at
+ *   - description
+ *   - id
+ *   - is_disabled
  *   - name
+ *   - updated_at
  * properties:
  *  id:
- *    type: string
  *    description: The sales channel's ID
+ *    type: string
  *    example: sc_01G8X9A7ESKAJXG2H0E6F1MW7A
  *  name:
- *    description: "The name of the sales channel."
+ *    description: The name of the sales channel.
  *    type: string
  *    example: Market
  *  description:
- *    description: "The description of the sales channel."
+ *    description: The description of the sales channel.
+ *    nullable: true
  *    type: string
  *    example: Multi-vendor market
  *  is_disabled:
- *    description: "Specify if the sales channel is enabled or disabled."
+ *    description: Specify if the sales channel is enabled or disabled.
  *    type: boolean
  *    default: false
  *  locations:
@@ -61,15 +68,16 @@ export class SalesChannel extends SoftDeletableEntity {
  *    items:
  *      $ref: "#/components/schemas/SalesChannelLocation"
  *  created_at:
+ *    description: The date with timezone at which the resource was created.
  *    type: string
- *    description: "The date with timezone at which the resource was created."
  *    format: date-time
  *  updated_at:
+ *    description: The date with timezone at which the resource was updated.
  *    type: string
- *    description: "The date with timezone at which the resource was updated."
  *    format: date-time
  *  deleted_at:
+ *    description: The date with timezone at which the resource was deleted.
+ *    nullable: true
  *    type: string
- *    description: "The date with timezone at which the resource was deleted."
  *    format: date-time
  */
diff --git a/packages/medusa/src/models/shipping-method-tax-line.ts b/packages/medusa/src/models/shipping-method-tax-line.ts
index d01a99fffc..dac24d4d09 100644
--- a/packages/medusa/src/models/shipping-method-tax-line.ts
+++ b/packages/medusa/src/models/shipping-method-tax-line.ts
@@ -35,43 +35,51 @@ export class ShippingMethodTaxLine extends TaxLine {
  * description: "Shipping Method Tax Line"
  * type: object
  * required:
+ *   - code
+ *   - created_at
+ *   - id
  *   - shipping_method_id
- *   - rate
+ *   - metadata
  *   - name
+ *   - rate
+ *   - updated_at
  * properties:
  *   id:
- *     type: string
  *     description: The line item tax line's ID
- *     example: smtl_01G1G5V2DRX1SK6NQQ8VVX4HQ8
- *   shipping_method_id:
  *     type: string
- *     description: The ID of the line item
- *     example: sm_01F0YET7DR2E7CYVSDHM593QG2
- *   shipping_method:
- *     description: Available if the relation `shipping_method` is expanded.
- *     $ref: "#/components/schemas/ShippingMethod"
+ *     example: smtl_01G1G5V2DRX1SK6NQQ8VVX4HQ8
  *   code:
- *     description: "A code to identify the tax type by"
+ *     description: A code to identify the tax type by
+ *     nullable: true
  *     type: string
  *     example: tax01
  *   name:
- *     description: "A human friendly name for the tax"
+ *     description: A human friendly name for the tax
  *     type: string
  *     example: Tax Example
  *   rate:
  *     description: "The numeric rate to charge tax by"
  *     type: number
  *     example: 10
- *   created_at:
+ *   shipping_method_id:
+ *     description: The ID of the line item
+ *     type: string
+ *     example: sm_01F0YET7DR2E7CYVSDHM593QG2
+ *   shipping_method:
+ *     description: Available if the relation `shipping_method` is expanded.
+ *     nullable: true
+ *     $ref: "#/components/schemas/ShippingMethod"
+ *   created_at:
+ *     description: The date with timezone at which the resource was created.
  *     type: string
- *     description: "The date with timezone at which the resource was created."
  *     format: date-time
  *   updated_at:
+ *     description: The date with timezone at which the resource was updated.
  *     type: string
- *     description: "The date with timezone at which the resource was updated."
  *     format: date-time
  *   metadata:
- *     type: object
  *     description: An optional key-value map with additional details
+ *     nullable: true
+ *     type: object
  *     example: {car: "white"}
  */
diff --git a/packages/medusa/src/models/shipping-method.ts b/packages/medusa/src/models/shipping-method.ts
index ac3227eb9b..0881ad021e 100644
--- a/packages/medusa/src/models/shipping-method.ts
+++ b/packages/medusa/src/models/shipping-method.ts
@@ -110,69 +110,100 @@ export class ShippingMethod {
  * 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."
  * type: object
  * required:
- *   - shipping_option_id
+ *   - cart_id
+ *   - claim_order_id
+ *   - data
+ *   - id
+ *   - order_id
  *   - price
+ *   - return_id
+ *   - shipping_option_id
+ *   - swap_id
  * properties:
  *   id:
- *     type: string
  *     description: The shipping method's ID
+ *     type: string
  *     example: sm_01F0YET7DR2E7CYVSDHM593QG2
  *   shipping_option_id:
- *     description: "The id of the Shipping Option that the Shipping Method is built from."
+ *     description: The id of the Shipping Option that the Shipping Method is built from.
  *     type: string
  *     example: so_01G1G5V27GYX4QXNARRQCW1N8T
- *   shipping_option:
- *     description: Available if the relation `shipping_option` is expanded.
- *     $ref: "#/components/schemas/ShippingOption"
  *   order_id:
- *     description: "The id of the Order that the Shipping Method is used on."
+ *     description: The id of the Order that the Shipping Method is used on.
+ *     nullable: true
  *     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
+ *     nullable: true
+ *     $ref: "#/components/schemas/Order"
  *   claim_order_id:
- *     description: "The id of the Claim that the Shipping Method is used on."
+ *     description: The id of the Claim that the Shipping Method is used on.
+ *     nullable: true
  *     type: string
  *     example: null
  *   claim_order:
  *     description: A claim order object. Available if the relation `claim_order` is expanded.
- *     type: object
+ *     nullable: true
+ *     $ref: "#/components/schemas/ClaimOrder"
+ *   cart_id:
+ *     description: The id of the Cart that the Shipping Method is used on.
+ *     nullable: true
+ *     type: string
+ *     example: cart_01G8ZH853Y6TFXWPG5EYE81X63
+ *   cart:
+ *     description: A cart object. Available if the relation `cart` is expanded.
+ *     nullable: true
+ *     $ref: "#/components/schemas/Cart"
+ *   swap_id:
+ *     description: The id of the Swap that the Shipping Method is used on.
+ *     nullable: true
+ *     type: string
+ *     example: null
+ *   swap:
+ *     description: A swap object. Available if the relation `swap` is expanded.
+ *     nullable: true
+ *     $ref: "#/components/schemas/Swap"
+ *   return_id:
+ *     description: The id of the Return that the Shipping Method is used on.
+ *     nullable: true
+ *     type: string
+ *     example: null
+ *   return_order:
+ *     description: A return object. Available if the relation `return_order` is expanded.
+ *     nullable: true
+ *     $ref: "#/components/schemas/Return"
+ *   shipping_option:
+ *     description: Available if the relation `shipping_option` is expanded.
+ *     nullable: true
+ *     $ref: "#/components/schemas/ShippingOption"
  *   tax_lines:
- *     type: array
  *     description: Available if the relation `tax_lines` is expanded.
+ *     type: array
  *     items:
  *       $ref: "#/components/schemas/ShippingMethodTaxLine"
  *   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."
+ *     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."
+ *     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: {}
  *   includes_tax:
  *     description: "[EXPERIMENTAL] Indicates if the shipping method price include tax"
  *     type: boolean
+ *     default: false
+ *   subtotal:
+ *     description: The subtotal of the shipping
+ *     type: integer
+ *     example: 8000
+ *   total:
+ *     description: The total amount of the shipping
+ *     type: integer
+ *     example: 8200
+ *   tax_total:
+ *     description: The total of tax
+ *     type: integer
+ *     example: 0
  */
diff --git a/packages/medusa/src/models/shipping-option-requirement.ts b/packages/medusa/src/models/shipping-option-requirement.ts
index a31c33f444..4d490684a8 100644
--- a/packages/medusa/src/models/shipping-option-requirement.ts
+++ b/packages/medusa/src/models/shipping-option-requirement.ts
@@ -52,34 +52,38 @@ export class ShippingOptionRequirement {
  * description: "A requirement that a Cart must satisfy for the Shipping Option to be available to the Cart."
  * type: object
  * required:
+ *   - amount
+ *   - deleted_at
+ *   - id
  *   - shipping_option_id
  *   - type
- *   - amount
  * properties:
  *   id:
- *     type: string
  *     description: The shipping option requirement's ID
+ *     type: string
  *     example: sor_01G1G5V29AB4CTNDRFSRWSRKWD
  *   shipping_option_id:
- *     description: "The id of the Shipping Option that the hipping option requirement belongs to"
+ *     description: The id of the Shipping Option that the hipping option requirement belongs to
  *     type: string
  *     example: so_01G1G5V27GYX4QXNARRQCW1N8T
  *   shipping_option:
  *     description: Available if the relation `shipping_option` is expanded.
+ *     nullable: true
  *     $ref: "#/components/schemas/ShippingOption"
  *   type:
- *     description: "The type of the requirement, this defines how the value will be compared to the Cart's total. `min_subtotal` requirements define the minimum subtotal that is needed for the Shipping Option to be available, while the `max_subtotal` defines the maximum subtotal that the Cart can have for the Shipping Option to be available."
+ *     description: The type of the requirement, this defines how the value will be compared to the Cart's total. `min_subtotal` requirements define the minimum subtotal that is needed for the Shipping Option to be available, while the `max_subtotal` defines the maximum subtotal that the Cart can have for the Shipping Option to be available.
  *     type: string
  *     enum:
  *       - min_subtotal
  *       - max_subtotal
  *     example: min_subtotal
  *   amount:
- *     description: "The amount to compare the Cart subtotal to."
+ *     description: The amount to compare the Cart subtotal to.
  *     type: integer
  *     example: 100
  *   deleted_at:
+ *     description: The date with timezone at which the resource was deleted.
+ *     nullable: true
  *     type: string
- *     description: "The date with timezone at which the resource was deleted."
  *     format: date-time
  */
diff --git a/packages/medusa/src/models/shipping-option.ts b/packages/medusa/src/models/shipping-option.ts
index 367a6111c1..8934661d71 100644
--- a/packages/medusa/src/models/shipping-option.ts
+++ b/packages/medusa/src/models/shipping-option.ts
@@ -92,54 +92,71 @@ export class ShippingOption extends SoftDeletableEntity {
  * description: "Shipping Options represent a way in which an Order or Return can be shipped. Shipping Options have an associated Fulfillment Provider that will be used when the fulfillment of an Order is initiated. Shipping Options themselves cannot be added to Carts, but serve as a template for Shipping Methods. This distinction makes it possible to customize individual Shipping Methods with additional information."
  * type: object
  * required:
+ *   - admin_only
+ *   - amount
+ *   - created_at
+ *   - data
+ *   - deleted_at
+ *   - id
+ *   - is_return
+ *   - metadata
  *   - name
- *   - region_id
+ *   - price_type
  *   - profile_id
  *   - provider_id
- *   - price_type
+ *   - region_id
+ *   - updated_at
  * properties:
  *   id:
- *     type: string
  *     description: The shipping option's ID
+ *     type: string
  *     example: so_01G1G5V27GYX4QXNARRQCW1N8T
  *   name:
- *     description: "The name given to the Shipping Option - this may be displayed to the Customer."
+ *     description: The name given to the Shipping Option - this may be displayed to the Customer.
  *     type: string
  *     example: PostFake Standard
  *   region_id:
- *     type: string
  *     description: The region's ID
+ *     type: string
  *     example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
  *   region:
  *     description: A region object. Available if the relation `region` is expanded.
- *     type: object
+ *     nullable: true
+ *     $ref: "#/components/schemas/Region"
  *   profile_id:
- *     description: "The ID of the Shipping Profile that the shipping option belongs to. Shipping Profiles have a set of defined Shipping Options that can be used to Fulfill a given set of Products."
+ *     description: The ID of the Shipping Profile that the shipping option belongs to. Shipping Profiles have a set of defined Shipping Options that can be used to Fulfill a given set of Products.
  *     type: string
  *     example: sp_01G1G5V239ENSZ5MV4JAR737BM
  *   profile:
  *     description: Available if the relation `profile` is expanded.
+ *     nullable: true
  *     $ref: "#/components/schemas/ShippingProfile"
  *   provider_id:
- *     description: "The id of the Fulfillment Provider, that will be used to process Fulfillments from the Shipping Option."
+ *     description: The id of the Fulfillment Provider, that will be used to process Fulfillments from the Shipping Option.
  *     type: string
  *     example: manual
  *   provider:
  *     description: Available if the relation `provider` is expanded.
+ *     nullable: true
  *     $ref: "#/components/schemas/FulfillmentProvider"
  *   price_type:
- *     description: "The type of pricing calculation that is used when creatin Shipping Methods from the Shipping Option. Can be `flat_rate` for fixed prices or `calculated` if the Fulfillment Provider can provide price calulations."
+ *     description: The type of pricing calculation that is used when creatin Shipping Methods from the Shipping Option. Can be `flat_rate` for fixed prices or `calculated` if the Fulfillment Provider can provide price calulations.
  *     type: string
  *     enum:
  *       - flat_rate
  *       - calculated
  *     example: flat_rate
  *   amount:
- *     description: "The amount to charge for shipping when the Shipping Option price type is `flat_rate`."
+ *     description: The amount to charge for shipping when the Shipping Option price type is `flat_rate`.
+ *     nullable: true
  *     type: integer
  *     example: 200
  *   is_return:
- *     description: "Flag to indicate if the Shipping Option can be used for Return shipments."
+ *     description: Flag to indicate if the Shipping Option can be used for Return shipments.
+ *     type: boolean
+ *     default: false
+ *   admin_only:
+ *     description: Flag to indicate if the Shipping Option usage is restricted to admin users.
  *     type: boolean
  *     default: false
  *   requirements:
@@ -148,26 +165,29 @@ export class ShippingOption extends SoftDeletableEntity {
  *     items:
  *       $ref: "#/components/schemas/ShippingOptionRequirement"
  *   data:
- *     description: "The data needed for the Fulfillment Provider to identify the Shipping Option."
+ *     description: The data needed for the Fulfillment Provider to identify the Shipping Option.
  *     type: object
  *     example: {}
  *   includes_tax:
  *     description: "[EXPERIMENTAL] Does the shipping option price include tax"
  *     type: boolean
+ *     default: false
  *   created_at:
+ *     description: The date with timezone at which the resource was created.
  *     type: string
- *     description: "The date with timezone at which the resource was created."
  *     format: date-time
  *   updated_at:
+ *     description: The date with timezone at which the resource was updated.
  *     type: string
- *     description: "The date with timezone at which the resource was updated."
  *     format: date-time
  *   deleted_at:
+ *     description: The date with timezone at which the resource was deleted.
+ *     nullable: true
  *     type: string
- *     description: "The date with timezone at which the resource was deleted."
  *     format: date-time
  *   metadata:
- *     type: object
  *     description: An optional key-value map with additional details
+ *     nullable: true
+ *     type: object
  *     example: {car: "white"}
  */
diff --git a/packages/medusa/src/models/shipping-profile.ts b/packages/medusa/src/models/shipping-profile.ts
index e2a14ff56e..abdc4bb8e3 100644
--- a/packages/medusa/src/models/shipping-profile.ts
+++ b/packages/medusa/src/models/shipping-profile.ts
@@ -41,19 +41,24 @@ export class ShippingProfile extends SoftDeletableEntity {
  * description: "Shipping Profiles have a set of defined Shipping Options that can be used to fulfill a given set of Products."
  * type: object
  * required:
+ *   - created_at
+ *   - deleted_at
+ *   - id
+ *   - metadata
  *   - name
  *   - type
+ *   - updated_at
  * properties:
  *   id:
- *     type: string
  *     description: The shipping profile's ID
+ *     type: string
  *     example: sp_01G1G5V239ENSZ5MV4JAR737BM
  *   name:
- *     description: "The name given to the Shipping profile - this may be displayed to the Customer."
+ *     description: The name given to the Shipping profile - this may be displayed to the Customer.
  *     type: string
  *     example: Default Shipping Profile
  *   type:
- *     description: "The type of the Shipping Profile, may be `default`, `gift_card` or `custom`."
+ *     description: The type of the Shipping Profile, may be `default`, `gift_card` or `custom`.
  *     type: string
  *     enum:
  *       - default
@@ -64,27 +69,28 @@ export class ShippingProfile extends SoftDeletableEntity {
  *     description: The Products that the Shipping Profile defines Shipping Options for. Available if the relation `products` is expanded.
  *     type: array
  *     items:
- *       type: object
- *       description: A product object.
+ *       $ref: "#/components/schemas/Product"
  *   shipping_options:
  *     description: The Shipping Options that can be used to fulfill the Products in the Shipping Profile. Available if the relation `shipping_options` is expanded.
  *     type: array
  *     items:
  *       $ref: "#/components/schemas/ShippingOption"
  *   created_at:
+ *     description: The date with timezone at which the resource was created.
  *     type: string
- *     description: "The date with timezone at which the resource was created."
  *     format: date-time
  *   updated_at:
+ *     description: The date with timezone at which the resource was updated.
  *     type: string
- *     description: "The date with timezone at which the resource was updated."
  *     format: date-time
  *   deleted_at:
+ *     description: The date with timezone at which the resource was deleted.
+ *     nullable: true
  *     type: string
- *     description: "The date with timezone at which the resource was deleted."
  *     format: date-time
  *   metadata:
- *     type: object
  *     description: An optional key-value map with additional details
+ *     nullable: true
+ *     type: object
  *     example: {car: "white"}
  */
diff --git a/packages/medusa/src/models/shipping-tax-rate.ts b/packages/medusa/src/models/shipping-tax-rate.ts
index 59f93bfcf4..bf3aa01579 100644
--- a/packages/medusa/src/models/shipping-tax-rate.ts
+++ b/packages/medusa/src/models/shipping-tax-rate.ts
@@ -43,33 +43,39 @@ export class ShippingTaxRate {
  * description: "Associates a tax rate with a shipping option to indicate that the shipping option is taxed in a certain way"
  * type: object
  * required:
- *   - shipping_option_id
+ *   - created_at
+ *   - metadata
  *   - rate_id
+ *   - shipping_option_id
+ *   - updated_at
  * properties:
  *   shipping_option_id:
- *     description: "The ID of the Shipping Option"
+ *     description: The ID of the Shipping Option
  *     type: string
  *     example: so_01G1G5V27GYX4QXNARRQCW1N8T
  *   shipping_option:
  *     description: Available if the relation `shipping_option` is expanded.
+ *     nullable: true
  *     $ref: "#/components/schemas/ShippingOption"
  *   rate_id:
- *     description: "The ID of the Tax Rate"
+ *     description: The ID of the Tax Rate
  *     type: string
  *     example: txr_01G8XDBAWKBHHJRKH0AV02KXBR
  *   tax_rate:
  *     description: Available if the relation `tax_rate` is expanded.
+ *     nullable: true
  *     $ref: "#/components/schemas/TaxRate"
  *   created_at:
+ *     description: The date with timezone at which the resource was created.
  *     type: string
- *     description: "The date with timezone at which the resource was created."
  *     format: date-time
  *   updated_at:
+ *     description: The date with timezone at which the resource was updated.
  *     type: string
- *     description: "The date with timezone at which the resource was updated."
  *     format: date-time
  *   metadata:
- *     type: object
  *     description: An optional key-value map with additional details
+ *     nullable: true
+ *     type: object
  *     example: {car: "white"}
  */
diff --git a/packages/medusa/src/models/staged-job.ts b/packages/medusa/src/models/staged-job.ts
index fb6004db48..8f7c8f86e6 100644
--- a/packages/medusa/src/models/staged-job.ts
+++ b/packages/medusa/src/models/staged-job.ts
@@ -29,18 +29,25 @@ export class StagedJob {
  * description: "A staged job resource"
  * type: object
  * required:
+ *   - data
  *   - event_name
+ *   - id
+ *   - options
  * properties:
  *   id:
- *     type: string
  *     description: The staged job's ID
+ *     type: string
  *     example: job_01F0YET7BZTARY9MKN1SJ7AAXF
  *   event_name:
- *     description: "The name of the event"
+ *     description: The name of the event
  *     type: string
  *     example: order.placed
  *   data:
  *     description: Data necessary for the job
  *     type: object
  *     example: {}
+ *   option:
+ *     description: The staged job's option
+ *     type: object
+ *     example: {}
  */
diff --git a/packages/medusa/src/models/store.ts b/packages/medusa/src/models/store.ts
index e8b046bff6..ed7de578d7 100644
--- a/packages/medusa/src/models/store.ts
+++ b/packages/medusa/src/models/store.ts
@@ -80,17 +80,28 @@ export class Store extends BaseEntity {
  * title: "Store"
  * description: "Holds settings for the Store, such as name, currencies, etc."
  * type: object
+ * required:
+ *   - created_at
+ *   - default_currency_code
+ *   - default_location_id
+ *   - id
+ *   - invite_link_template
+ *   - metadata
+ *   - name
+ *   - payment_link_template
+ *   - swap_link_template
+ *   - updated_at
  * properties:
  *   id:
- *     type: string
  *     description: The store's ID
+ *     type: string
  *     example: store_01G1G5V21KADXNGH29BJMAJ4B4
  *   name:
- *     description: "The name of the Store - this may be displayed to the Customer."
+ *     description: The name of the Store - this may be displayed to the Customer.
  *     type: string
  *     example: Medusa Store
  *   default_currency_code:
- *     description: "The 3 character currency code that is the default of the store."
+ *     description: The 3 character currency code that is the default of the store.
  *     type: string
  *     example: usd
  *     externalDocs:
@@ -98,6 +109,7 @@ export class Store extends BaseEntity {
  *       description: See a list of codes.
  *   default_currency:
  *     description: Available if the relation `default_currency` is expanded.
+ *     nullable: true
  *     $ref: "#/components/schemas/Currency"
  *   currencies:
  *     description: The currencies that are enabled for the Store. Available if the relation `currencies` is expanded.
@@ -105,26 +117,45 @@ export class Store extends BaseEntity {
  *     items:
  *       $ref: "#/components/schemas/Currency"
  *   swap_link_template:
- *     description: "A template to generate Swap links from. Use {{cart_id}} to include the Swap's `cart_id` in the link."
+ *     description: A template to generate Swap links from. Use {{cart_id}} to include the Swap's `cart_id` in the link.
+ *     nullable: true
  *     type: string
  *     example: null
  *   payment_link_template:
- *     description: "A template to generate Payment links from. Use {{cart_id}} to include the payment's `cart_id` in the link."
+ *     description: A template to generate Payment links from. Use {{cart_id}} to include the payment's `cart_id` in the link.
+ *     nullable: true
  *     type: string
  *     example: null
  *   invite_link_template:
- *     description: "A template to generate Invite links from"
+ *     description: A template to generate Invite links from
+ *     nullable: true
+ *     type: string
+ *     example: null
+ *   default_location_id:
+ *     description: The location ID the store is associated with.
+ *     nullable: true
  *     type: string
  *     example: null
  *   default_sales_channel_id:
- *     type: string
  *     description: The sales channel ID the cart is associated with.
+ *     nullable: true
+ *     type: string
  *     example: null
  *   default_sales_channel:
  *     description: A sales channel object. Available if the relation `default_sales_channel` is expanded.
- *     type: object
+ *     nullable: true
+ *     $ref: "#/components/schemas/SalesChannel"
+ *   created_at:
+ *     description: The date with timezone at which the resource was created.
+ *     type: string
+ *     format: date-time
+ *   updated_at:
+ *     description: The date with timezone at which the resource was updated.
+ *     type: string
+ *     format: date-time
  *   metadata:
- *     type: object
  *     description: An optional key-value map with additional details
+ *     nullable: true
+ *     type: object
  *     example: {car: "white"}
  */
diff --git a/packages/medusa/src/models/swap.ts b/packages/medusa/src/models/swap.ts
index e02ef3b7ed..e60fd65ac2 100644
--- a/packages/medusa/src/models/swap.ts
+++ b/packages/medusa/src/models/swap.ts
@@ -124,26 +124,40 @@ export class Swap extends SoftDeletableEntity {
  * description: "Swaps can be created when a Customer wishes to exchange Products that they have purchased to different Products. Swaps consist of a Return of previously purchased Products and a Fulfillment of new Products, the amount paid for the Products being returned will be used towards payment for the new Products. In the case where the amount paid for the the Products being returned exceed the amount to be paid for the new Products, a Refund will be issued for the difference."
  * type: object
  * required:
+ *   - allow_backorder
+ *   - canceled_at
+ *   - cart_id
+ *   - confirmed_at
+ *   - created_at
+ *   - deleted_at
+ *   - difference_due
  *   - fulfillment_status
- *   - payment_status
+ *   - id
+ *   - idempotency_key
+ *   - metadata
+ *   - no_notification
  *   - order_id
+ *   - payment_status
+ *   - shipping_address_id
+ *   - updated_at
  * properties:
  *   id:
- *     type: string
  *     description: The swap's ID
+ *     type: string
  *     example: swap_01F0YET86Y9G92D3YDR9Y6V676
  *   fulfillment_status:
- *     description: "The status of the Fulfillment of the Swap."
+ *     description: The status of the Fulfillment of the Swap.
  *     type: string
  *     enum:
  *       - not_fulfilled
  *       - fulfilled
  *       - shipped
+ *       - partially_shipped
  *       - canceled
  *       - requires_action
  *     example: not_fulfilled
  *   payment_status:
- *     description: "The status of the Payment of the Swap. The payment may either refer to the refund of an amount or the authorization of a new amount."
+ *     description: The status of the Payment of the Swap. The payment may either refer to the refund of an amount or the authorization of a new amount.
  *     type: string
  *     enum:
  *       - not_paid
@@ -157,12 +171,13 @@ export class Swap extends SoftDeletableEntity {
  *       - requires_action
  *     example: not_paid
  *   order_id:
- *     description: "The ID of the Order where the Line Items to be returned where purchased."
+ *     description: The ID of the Order where the Line Items to be returned where purchased.
  *     type: string
  *     example: order_01G8TJSYT9M6AVS5N4EMNFS1EK
  *   order:
  *     description: An order object. Available if the relation `order` is expanded.
- *     type: object
+ *     nullable: true
+ *     $ref: "#/components/schemas/Order"
  *   additional_items:
  *     description: The new Line Items to ship to the Customer. Available if the relation `additional_items` is expanded.
  *     type: array
@@ -170,7 +185,8 @@ export class Swap extends SoftDeletableEntity {
  *       $ref: "#/components/schemas/LineItem"
  *   return_order:
  *     description: A return order object. The Return that is issued for the return part of the Swap. Available if the relation `return_order` is expanded.
- *     type: object
+ *     nullable: true
+ *     $ref: "#/components/schemas/Return"
  *   fulfillments:
  *     description: The Fulfillments used to send the new Line Items. Available if the relation `fulfillments` is expanded.
  *     type: array
@@ -178,17 +194,21 @@ export class Swap extends SoftDeletableEntity {
  *       $ref: "#/components/schemas/Fulfillment"
  *   payment:
  *     description: The Payment authorized when the Swap requires an additional amount to be charged from the Customer. Available if the relation `payment` is expanded.
+ *     nullable: true
  *     $ref: "#/components/schemas/Payment"
  *   difference_due:
- *     description: "The difference that is paid or refunded as a result of the Swap. May be negative when the amount paid for the returned items exceed the total of the new Products."
+ *     description: The difference that is paid or refunded as a result of the Swap. May be negative when the amount paid for the returned items exceed the total of the new Products.
+ *     nullable: true
  *     type: integer
  *     example: 0
  *   shipping_address_id:
  *     description: The Address to send the new Line Items to - in most cases this will be the same as the shipping address on the Order.
+ *     nullable: true
  *     type: string
  *     example: addr_01G8ZH853YPY9B94857DY91YGW
  *   shipping_address:
  *     description: Available if the relation `shipping_address` is expanded.
+ *     nullable: true
  *     $ref: "#/components/schemas/Address"
  *   shipping_methods:
  *     description: The Shipping Methods used to fulfill the additional items purchased. Available if the relation `shipping_methods` is expanded.
@@ -196,48 +216,56 @@ export class Swap extends SoftDeletableEntity {
  *     items:
  *       $ref: "#/components/schemas/ShippingMethod"
  *   cart_id:
- *     description: "The id of the Cart that the Customer will use to confirm the Swap."
+ *     description: The id of the Cart that the Customer will use to confirm the Swap.
+ *     nullable: true
  *     type: string
  *     example: cart_01G8ZH853Y6TFXWPG5EYE81X63
  *   cart:
  *     description: A cart object. Available if the relation `cart` is expanded.
- *     type: object
- *   allow_backorder:
- *     description: "If true, swaps can be completed with items out of stock"
- *     type: boolean
- *     default: false
- *   idempotency_key:
- *     type: string
- *     description: Randomly generated key used to continue the completion of the swap in case of failure.
- *     externalDocs:
- *       url: https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key
- *       description: Learn more how to use the idempotency key.
+ *     nullable: true
+ *     $ref: "#/components/schemas/Cart"
  *   confirmed_at:
- *     description: "The date with timezone at which the Swap was confirmed by the Customer."
+ *     description: The date with timezone at which the Swap was confirmed by the Customer.
+ *     nullable: true
  *     type: string
  *     format: date-time
  *   canceled_at:
- *     description: "The date with timezone at which the Swap was canceled."
+ *     description: The date with timezone at which the Swap was canceled.
+ *     nullable: true
  *     type: string
  *     format: date-time
  *   no_notification:
- *     description: "If set to true, no notification will be sent related to this swap"
+ *     description: If set to true, no notification will be sent related to this swap
+ *     nullable: true
  *     type: boolean
  *     example: false
- *   created_at:
+ *   allow_backorder:
+ *     description: If true, swaps can be completed with items out of stock
+ *     type: boolean
+ *     default: false
+ *   idempotency_key:
+ *     description: Randomly generated key used to continue the completion of the swap in case of failure.
+ *     nullable: true
+ *     type: string
+ *     externalDocs:
+ *       url: https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key
+ *       description: Learn more how to use the idempotency key.
+ *   created_at:
+ *     description: The date with timezone at which the resource was created.
  *     type: string
- *     description: "The date with timezone at which the resource was created."
  *     format: date-time
  *   updated_at:
+ *     description: The date with timezone at which the resource was updated.
  *     type: string
- *     description: "The date with timezone at which the resource was updated."
  *     format: date-time
  *   deleted_at:
+ *     description: The date with timezone at which the resource was deleted.
+ *     nullable: true
  *     type: string
- *     description: "The date with timezone at which the resource was deleted."
  *     format: date-time
  *   metadata:
- *     type: object
  *     description: An optional key-value map with additional details
+ *     nullable: true
+ *     type: object
  *     example: {car: "white"}
  */
diff --git a/packages/medusa/src/models/tax-line.ts b/packages/medusa/src/models/tax-line.ts
index 67d7038479..3bdb268854 100644
--- a/packages/medusa/src/models/tax-line.ts
+++ b/packages/medusa/src/models/tax-line.ts
@@ -22,35 +22,42 @@ export class TaxLine extends BaseEntity {
  * description: "Line item that specifies an amount of tax to add to a line item."
  * type: object
  * required:
- *   - rate
+ *   - code
+ *   - created_at
+ *   - id
+ *   - metadata
  *   - name
+ *   - rate
+ *   - updated_at
  * properties:
  *   id:
- *     type: string
  *     description: The tax line's ID
+ *     type: string
  *     example: tl_01G1G5V2DRX1SK6NQQ8VVX4HQ8
  *   code:
- *     description: "A code to identify the tax type by"
+ *     description: A code to identify the tax type by
+ *     nullable: true
  *     type: string
  *     example: tax01
  *   name:
- *     description: "A human friendly name for the tax"
+ *     description: A human friendly name for the tax
  *     type: string
  *     example: Tax Example
  *   rate:
- *     description: "The numeric rate to charge tax by"
+ *     description: The numeric rate to charge tax by
  *     type: number
  *     example: 10
  *   created_at:
+ *     description: The date with timezone at which the resource was created.
  *     type: string
- *     description: "The date with timezone at which the resource was created."
  *     format: date-time
  *   updated_at:
+ *     description: The date with timezone at which the resource was updated.
  *     type: string
- *     description: "The date with timezone at which the resource was updated."
  *     format: date-time
  *   metadata:
- *     type: object
  *     description: An optional key-value map with additional details
+ *     nullable: true
+ *     type: object
  *     example: {car: "white"}
  */
diff --git a/packages/medusa/src/models/tax-provider.ts b/packages/medusa/src/models/tax-provider.ts
index fb28032e81..40b0612146 100644
--- a/packages/medusa/src/models/tax-provider.ts
+++ b/packages/medusa/src/models/tax-provider.ts
@@ -14,13 +14,16 @@ export class TaxProvider {
  * title: "Tax Provider"
  * description: "The tax service used to calculate taxes"
  * type: object
+ * required:
+ *   - id
+ *   - is_installed
  * properties:
  *   id:
- *     description: "The id of the tax provider as given by the plugin."
+ *     description: The id of the tax provider as given by the plugin.
  *     type: string
  *     example: manual
  *   is_installed:
- *     description: "Whether the plugin is installed in the current version. Plugins that are no longer installed are not deleted by will have this field set to `false`."
+ *     description: Whether the plugin is installed in the current version. Plugins that are no longer installed are not deleted by will have this field set to `false`.
  *     type: boolean
  *     default: true
  */
diff --git a/packages/medusa/src/models/tax-rate.ts b/packages/medusa/src/models/tax-rate.ts
index c4853602fa..e892a6f210 100644
--- a/packages/medusa/src/models/tax-rate.ts
+++ b/packages/medusa/src/models/tax-rate.ts
@@ -96,72 +96,79 @@ export class TaxRate extends BaseEntity {
  * description: "A Tax Rate can be used to associate a certain rate to charge on products within a given Region"
  * type: object
  * required:
+ *   - code
+ *   - created_at
+ *   - id
+ *   - metadata
  *   - name
+ *   - rate
  *   - region_id
+ *   - updated_at
  * properties:
  *   id:
- *     type: string
  *     description: The tax rate's ID
+ *     type: string
  *     example: txr_01G8XDBAWKBHHJRKH0AV02KXBR
  *   rate:
- *     description: "The numeric rate to charge"
+ *     description: The numeric rate to charge
+ *     nullable: true
  *     type: number
  *     example: 10
  *   code:
- *     description: "A code to identify the tax type by"
+ *     description: A code to identify the tax type by
+ *     nullable: true
  *     type: string
  *     example: tax01
  *   name:
- *     description: "A human friendly name for the tax"
+ *     description: A human friendly name for the tax
  *     type: string
  *     example: Tax Example
  *   region_id:
+ *     description: The id of the Region that the rate belongs to
  *     type: string
- *     description: "The id of the Region that the rate belongs to"
  *     example: reg_01G1G5V26T9H8Y0M4JNE3YGA4G
  *   region:
  *     description: A region object. Available if the relation `region` is expanded.
- *     type: object
+ *     nullable: true
+ *     $ref: "#/components/schemas/Region"
  *   products:
- *     type: array
  *     description: The products that belong to this tax rate. Available if the relation `products` is expanded.
- *     items:
- *       type: object
- *       description: A product object.
- *   product_types:
  *     type: array
- *     description: The product types that belong to this tax rate. Available if the relation `product_types` is expanded.
  *     items:
- *       type: object
- *       description: A product type object.
+ *       $ref: "#/components/schemas/Product"
+ *   product_types:
+ *     description: The product types that belong to this tax rate. Available if the relation `product_types` is expanded.
+ *     type: array
+ *     items:
+ *       $ref: "#/components/schemas/ProductType"
  *   shipping_options:
  *     type: array
  *     description: The shipping options that belong to this tax rate. Available if the relation `shipping_options` is expanded.
  *     items:
- *       type: object
- *       description: A shipping option object.
+ *       $ref: "#/components/schemas/ShippingOption"
  *   product_count:
- *     description: "The count of products"
+ *     description: The count of products
  *     type: integer
- *     example: null
+ *     example: 10
  *   product_type_count:
- *     description: "The count of product types"
+ *     description: The count of product types
  *     type: integer
- *     example: null
+ *     example: 2
  *   shipping_option_count:
- *     description: "The count of shipping options"
+ *     description: The count of shipping options
  *     type: integer
- *     example: null
+ *     example: 1
  *   created_at:
+ *     description: The date with timezone at which the resource was created.
  *     type: string
- *     description: "The date with timezone at which the resource was created."
  *     format: date-time
  *   updated_at:
+ *     description: The date with timezone at which the resource was updated.
  *     type: string
- *     description: "The date with timezone at which the resource was updated."
  *     format: date-time
  *   metadata:
- *     type: object
  *     description: An optional key-value map with additional details
+ *     nullable: true
+ *     type: object
  *     example: {car: "white"}
  */
diff --git a/packages/medusa/src/models/tracking-link.ts b/packages/medusa/src/models/tracking-link.ts
index ae847e1c70..8ff4b9a5bc 100644
--- a/packages/medusa/src/models/tracking-link.ts
+++ b/packages/medusa/src/models/tracking-link.ts
@@ -38,48 +38,60 @@ export class TrackingLink extends SoftDeletableEntity {
  * description: "Tracking Link holds information about tracking numbers for a Fulfillment. Tracking Links can optionally contain a URL that can be visited to see the status of the shipment."
  * type: object
  * required:
- *   - tracking_number
+ *   - created_at
+ *   - deleted_at
  *   - fulfillment_id
+ *   - id
+ *   - idempotency_key
+ *   - metadata
+ *   - tracking_number
+ *   - updated_at
+ *   - url
  * properties:
  *   id:
- *     type: string
  *     description: The tracking link's ID
+ *     type: string
  *     example: tlink_01G8ZH853Y6TFXWPG5EYE81X63
  *   url:
- *     description: "The URL at which the status of the shipment can be tracked."
+ *     description: The URL at which the status of the shipment can be tracked.
+ *     nullable: true
  *     type: string
  *     format: uri
  *   tracking_number:
- *     description: "The tracking number given by the shipping carrier."
+ *     description: The tracking number given by the shipping carrier.
  *     type: string
  *     format: RH370168054CN
  *   fulfillment_id:
+ *     description: The id of the Fulfillment that the Tracking Link references.
  *     type: string
- *     description: "The id of the Fulfillment that the Tracking Link references."
  *     example: ful_01G8ZRTMQCA76TXNAT81KPJZRF
  *   fulfillment:
  *     description: Available if the relation `fulfillment` is expanded.
+ *     nullable: true
  *     $ref: "#/components/schemas/Fulfillment"
  *   idempotency_key:
- *     type: string
  *     description: Randomly generated key used to continue the completion of a process in case of failure.
+ *     nullable: true
+ *     type: string
  *     externalDocs:
  *       url: https://docs.medusajs.com/advanced/backend/payment/overview#idempotency-key
  *       description: Learn more how to use the idempotency key.
  *   created_at:
+ *     description: The date with timezone at which the resource was created.
  *     type: string
- *     description: "The date with timezone at which the resource was created."
  *     format: date-time
  *   updated_at:
+ *     description: The date with timezone at which the resource was updated.
  *     type: string
- *     description: "The date with timezone at which the resource was updated."
  *     format: date-time
  *   deleted_at:
+ *     description: The date with timezone at which the resource was deleted.
+ *     nullable: true
  *     type: string
- *     description: "The date with timezone at which the resource was deleted."
  *     format: date-time
  *   metadata:
- *     type: object
  *     description: An optional key-value map with additional details
+ *     nullable: true
+ *     type: object
  *     example: {car: "white"}
  */
diff --git a/packages/medusa/src/models/user.ts b/packages/medusa/src/models/user.ts
index 16c073b1ff..df43765cb7 100644
--- a/packages/medusa/src/models/user.ts
+++ b/packages/medusa/src/models/user.ts
@@ -51,42 +51,64 @@ export class User extends SoftDeletableEntity {
  * description: "Represents a User who can manage store settings."
  * type: object
  * required:
+ *   - api_token
+ *   - created_at
+ *   - deleted_at
  *   - email
+ *   - first_name
+ *   - id
+ *   - last_name
+ *   - metadata
+ *   - role
+ *   - updated_at
  * properties:
  *   id:
- *     type: string
  *     description: The user's ID
+ *     type: string
  *     example: usr_01G1G5V26F5TB3GPAPNJ8X1S3V
+ *   role:
+ *     description: The user's role
+ *     type: string
+ *     enum:
+ *       - admin
+ *       - member
+ *       - developer
+ *     default: member
  *   email:
- *     description: "The email of the User"
+ *     description: The email of the User
  *     type: string
  *     format: email
  *   first_name:
- *     description: "The first name of the User"
+ *     description: The first name of the User
+ *     nullable: true
  *     type: string
  *     example: Levi
  *   last_name:
- *     description: "The last name of the User"
+ *     description: The last name of the User
+ *     nullable: true
  *     type: string
  *     example: Bogan
  *   api_token:
  *     description: An API token associated with the user.
+ *     nullable: true
  *     type: string
  *     example: null
  *   created_at:
+ *     description: The date with timezone at which the resource was created.
  *     type: string
- *     description: "The date with timezone at which the resource was created."
  *     format: date-time
  *   updated_at:
+ *     description: The date with timezone at which the resource was updated.
  *     type: string
- *     description: "The date with timezone at which the resource was updated."
  *     format: date-time
  *   deleted_at:
+ *     description: The date with timezone at which the resource was deleted.
+ *     nullable: true
  *     type: string
- *     description: "The date with timezone at which the resource was deleted."
  *     format: date-time
  *   metadata:
- *     type: object
  *     description: An optional key-value map with additional details
+ *     nullable: true
+ *     type: object
  *     example: {car: "white"}
  */