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

docs/api/store/paths/carts_{id}_complete.yaml

@@ -0,0 +1,64 @@
+post:
+  summary: Complete a Cart
+  operationId: PostCartsCartComplete
+  description: >-
+    Completes a cart. The following steps will be performed. Payment
+    authorization is attempted and if more work is required, we simply return
+    the cart for further updates. If payment is authorized and order is not yet
+    created, we make sure to do so. The completion of a cart can be performed
+    idempotently with a provided header `Idempotency-Key`. If not provided, we
+    will generate one for the request.
+  parameters:
+    - in: path
+      name: id
+      required: true
+      description: The Cart id.
+      schema:
+        type: string
+  tags:
+    - Cart
+  responses:
+    '200':
+      description: >-
+        If a cart was successfully authorized, but requires further action from
+        the user the response body will contain the cart with an updated payment
+        session. If the Cart was successfully completed the response body will
+        contain the newly created Order.
+      content:
+        application/json:
+          schema:
+            properties:
+              type:
+                type: string
+                description: The type of the data property.
+                enum:
+                  - order
+                  - cart
+                  - swap
+              data:
+                type: object
+                description: >-
+                  The data of the result object. Its type depends on the type
+                  field.
+                oneOf:
+                  - type: object
+                    description: >-
+                      Cart was successfully authorized and order was placed
+                      successfully.
+                    properties:
+                      order:
+                        $ref: ../components/schemas/order.yaml
+                  - type: object
+                    description: >-
+                      Cart was successfully authorized but requires further
+                      actions.
+                    properties:
+                      cart:
+                        $ref: ../components/schemas/cart.yaml
+                  - type: object
+                    description: >-
+                      When cart is used for a swap and it has been completed
+                      successfully.
+                    properties:
+                      cart:
+                        $ref: ../components/schemas/swap.yaml