chore(docs): Generated API Reference (#2417)

Co-authored-by: shahednasser <shahednasser@users.noreply.github.com>

docs/api/store/components/schemas/address_fields.yaml

@@ -0,0 +1,53 @@
+title: Address Fields
+description: Address fields used when creating/updating an address.
+x-resourceId: address
+properties:
+  company:
+    type: string
+    description: Company name
+    example: Acme
+  first_name:
+    type: string
+    description: First name
+    example: Arno
+  last_name:
+    type: string
+    description: Last name
+    example: Willms
+  address_1:
+    type: string
+    description: Address line 1
+    example: 14433 Kemmer Court
+  address_2:
+    type: string
+    description: Address line 2
+    example: Suite 369
+  city:
+    type: string
+    description: City
+    example: South Geoffreyview
+  country_code:
+    type: string
+    description: The 2 character ISO code of the country in lower case
+    externalDocs:
+      url: >-
+        https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
+      description: See a list of codes.
+    example: st
+  province:
+    type: string
+    description: Province
+    example: Kentucky
+  postal_code:
+    type: string
+    description: Postal Code
+    example: 72093
+  phone:
+    type: string
+    description: Phone Number
+    example: 16128234334802
+  metadata:
+    type: object
+    description: An optional key-value map with additional details
+    example:
+      car: white

docs/api/store/components/schemas/product_variant_prices_fields.yaml

@@ -0,0 +1,37 @@
+title: Product Variant Prices Fields
+description: Product Variants Prices Fields that are only available in some requests.
+x-resourceId: product_variant_prices_fields
+properties:
+  original_price:
+    type: number
+    description: The original price of the variant without any discounted prices applied.
+  calculated_price:
+    type: number
+    description: The calculated price of the variant. Can be a discounted price.
+  original_price_incl_tax:
+    type: number
+    description: The original price of the variant including taxes.
+  calculated_price_incl_tax:
+    type: number
+    description: The calculated price of the variant including taxes.
+  original_tax:
+    type: number
+    description: The taxes applied on the original price.
+  calculated_tax:
+    type: number
+    description: The taxes applied on the calculated price.
+  tax_rates:
+    type: array
+    description: An array of applied tax rates
+    items:
+      type: object
+      properties:
+        rate:
+          type: number
+          description: The tax rate value
+        name:
+          type: string
+          description: The name of the tax rate
+        code:
+          type: string
+          description: The code of the tax rate

docs/api/store/openapi.yaml

@@ -149,40 +149,6 @@ paths:
     $ref: paths/auth.yaml
   /auth/{email}:
     $ref: paths/auth_{email}.yaml
-  /gift-cards/{code}:
-    $ref: paths/gift-cards_{code}.yaml
-  /collections/{id}:
-    $ref: paths/collections_{id}.yaml
-  /collections:
-    $ref: paths/collections.yaml
-  /customers/me/addresses:
-    $ref: paths/customers_me_addresses.yaml
-  /customers:
-    $ref: paths/customers.yaml
-  /customers/me/addresses/{address_id}:
-    $ref: paths/customers_me_addresses_{address_id}.yaml
-  /customers/me:
-    $ref: paths/customers_me.yaml
-  /customers/me/payment-methods:
-    $ref: paths/customers_me_payment-methods.yaml
-  /customers/me/orders:
-    $ref: paths/customers_me_orders.yaml
-  /customers/password-token:
-    $ref: paths/customers_password-token.yaml
-  /customers/password-reset:
-    $ref: paths/customers_password-reset.yaml
-  /order-edits/{id}/complete:
-    $ref: paths/order-edits_{id}_complete.yaml
-  /order-edits/{id}/decline:
-    $ref: paths/order-edits_{id}_decline.yaml
-  /order-edits/{id}:
-    $ref: paths/order-edits_{id}.yaml
-  /orders/cart/{cart_id}:
-    $ref: paths/orders_cart_{cart_id}.yaml
-  /orders/{id}:
-    $ref: paths/orders_{id}.yaml
-  /orders:
-    $ref: paths/orders.yaml
   /carts/{id}/shipping-methods:
     $ref: paths/carts_{id}_shipping-methods.yaml
   /carts/{id}/taxes:
@@ -207,6 +173,40 @@ paths:
     $ref: paths/carts_{id}_payment-sessions_{provider_id}_refresh.yaml
   /carts/{id}/payment-session:
     $ref: paths/carts_{id}_payment-session.yaml
+  /collections/{id}:
+    $ref: paths/collections_{id}.yaml
+  /collections:
+    $ref: paths/collections.yaml
+  /customers/me/addresses:
+    $ref: paths/customers_me_addresses.yaml
+  /customers:
+    $ref: paths/customers.yaml
+  /customers/me/addresses/{address_id}:
+    $ref: paths/customers_me_addresses_{address_id}.yaml
+  /customers/me:
+    $ref: paths/customers_me.yaml
+  /customers/me/payment-methods:
+    $ref: paths/customers_me_payment-methods.yaml
+  /customers/me/orders:
+    $ref: paths/customers_me_orders.yaml
+  /customers/password-token:
+    $ref: paths/customers_password-token.yaml
+  /customers/password-reset:
+    $ref: paths/customers_password-reset.yaml
+  /gift-cards/{code}:
+    $ref: paths/gift-cards_{code}.yaml
+  /order-edits/{id}/complete:
+    $ref: paths/order-edits_{id}_complete.yaml
+  /order-edits/{id}/decline:
+    $ref: paths/order-edits_{id}_decline.yaml
+  /order-edits/{id}:
+    $ref: paths/order-edits_{id}.yaml
+  /orders/cart/{cart_id}:
+    $ref: paths/orders_cart_{cart_id}.yaml
+  /orders/{id}:
+    $ref: paths/orders_{id}.yaml
+  /orders:
+    $ref: paths/orders.yaml
   /products/{id}:
     $ref: paths/products_{id}.yaml
   /products:

docs/api/store/paths/customers_me.yaml

@@ -58,7 +58,7 @@ post:
             billing_address:
               description: The Address to be used for billing purposes.
               anyOf:
-                - $ref: ../components/schemas/address.yaml
+                - $ref: ../components/schemas/address_fields.yaml
                   description: The full billing address object
                 - type: string
                   description: The ID of an existing billing address

docs/api/store/paths/customers_me_addresses.yaml

@@ -12,8 +12,16 @@ post:
           properties:
             address:
               description: The Address to add to the Customer.
-              anyOf:
-                - $ref: ../components/schemas/address.yaml
+              allOf:
+                - $ref: ../components/schemas/address_fields.yaml
+                - type: object
+                  required:
+                    - first_name
+                    - last_name
+                    - address_1
+                    - city
+                    - country_code
+                    - postal_code
   x-codeSamples:
     - lang: JavaScript
       label: JS Client

docs/api/store/paths/customers_me_addresses_{address_id}.yaml

@@ -63,7 +63,7 @@ post:
       application/json:
         schema:
           anyOf:
-            - $ref: ../components/schemas/address.yaml
+            - $ref: ../components/schemas/address_fields.yaml
   x-codeSamples:
     - lang: JavaScript
       label: JS Client

docs/api/store/paths/products.yaml

@@ -155,7 +155,17 @@ get:
               products:
                 type: array
                 items:
-                  $ref: ../components/schemas/product.yaml
+                  allOf:
+                    - $ref: ../components/schemas/product.yaml
+                    - type: object
+                      properties:
+                        variants:
+                          type: array
+                          items:
+                            allOf:
+                              - $ref: ../components/schemas/product_variant.yaml
+                              - $ref: >-
+                                  ../components/schemas/product_variant_prices_fields.yaml
               count:
                 type: integer
                 description: The total number of items available

docs/api/store/paths/products_{id}.yaml

@@ -52,7 +52,17 @@ get:
           schema:
             properties:
               product:
-                $ref: ../components/schemas/product.yaml
+                allOf:
+                  - $ref: ../components/schemas/product.yaml
+                  - type: object
+                    properties:
+                      variants:
+                        type: array
+                        items:
+                          allOf:
+                            - $ref: ../components/schemas/product_variant.yaml
+                            - $ref: >-
+                                ../components/schemas/product_variant_prices_fields.yaml
     '400':
       $ref: ../components/responses/400_error.yaml
     '404':

docs/api/store/paths/variants.yaml

@@ -79,7 +79,9 @@ get:
               variants:
                 type: array
                 items:
-                  $ref: ../components/schemas/product_variant.yaml
+                  allOf:
+                    - $ref: ../components/schemas/product_variant.yaml
+                    - $ref: ../components/schemas/product_variant_prices_fields.yaml
     '400':
       $ref: ../components/responses/400_error.yaml
     '404':

docs/api/store/paths/variants_{variant_id}.yaml

@@ -44,7 +44,9 @@ get:
           schema:
             properties:
               variant:
-                $ref: ../components/schemas/product_variant.yaml
+                allOf:
+                  - $ref: ../components/schemas/product_variant.yaml
+                  - $ref: ../components/schemas/product_variant_prices_fields.yaml
     '400':
       $ref: ../components/responses/400_error.yaml
     '404':