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

docs/api/admin/paths/order_{id}_swaps.yaml

@@ -0,0 +1,107 @@
+post:
+  operationId: PostOrdersOrderSwaps
+  summary: Create a Swap
+  description: >-
+    Creates a Swap. Swaps are used to handle Return of previously purchased
+    goods and Fulfillment of replacements simultaneously.
+  x-authenticated: true
+  parameters:
+    - in: path
+      name: id
+      required: true
+      description: The ID of the Order.
+      schema:
+        type: string
+  requestBody:
+    content:
+      application/json:
+        schema:
+          required:
+            - return_items
+          properties:
+            return_items:
+              description: The Line Items to return as part of the Swap.
+              type: array
+              items:
+                required:
+                  - item_id
+                  - quantity
+                properties:
+                  item_id:
+                    description: The ID of the Line Item that will be claimed.
+                    type: string
+                  quantity:
+                    description: The number of items that will be returned
+                    type: integer
+                  reason_id:
+                    description: The ID of the Return Reason to use.
+                    type: string
+                  note:
+                    description: An optional note with information about the Return.
+                    type: string
+            return_shipping:
+              description: How the Swap will be returned.
+              type: object
+              required:
+                - option_id
+              properties:
+                option_id:
+                  type: string
+                  description: >-
+                    The ID of the Shipping Option to create the Shipping Method
+                    from.
+                price:
+                  type: integer
+                  description: The price to charge for the Shipping Method.
+            additional_items:
+              description: The new items to send to the Customer.
+              type: array
+              items:
+                required:
+                  - variant_id
+                  - quantity
+                properties:
+                  variant_id:
+                    description: The ID of the Product Variant to ship.
+                    type: string
+                  quantity:
+                    description: The quantity of the Product Variant to ship.
+                    type: integer
+            custom_shipping_options:
+              description: >-
+                The custom shipping options to potentially create a Shipping
+                Method from.
+              type: array
+              items:
+                required:
+                  - option_id
+                  - price
+                properties:
+                  option_id:
+                    description: >-
+                      The ID of the Shipping Option to override with a custom
+                      price.
+                    type: string
+                  price:
+                    description: The custom price of the Shipping Option.
+                    type: integer
+            no_notification:
+              description: >-
+                If set to true no notification will be send related to this
+                Swap.
+              type: boolean
+            allow_backorder:
+              description: If true, swaps can be completed with items out of stock
+              type: boolean
+              default: true
+  tags:
+    - Swap
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            properties:
+              order:
+                $ref: ../components/schemas/order.yaml