feat: Documentation and API reference (#348)

Co-authored-by: Vadim Smirnov <smirnou.vadzim@gmail.com>
Co-authored-by: zakariasaad <zakaria.elas@gmail.com>
Co-authored-by: Vilfred Sikker <vilfredsikker@gmail.com>
Co-authored-by: Kasper <kasper@medusa-commerce.com>
Co-authored-by: Sebastian Rindom <skrindom@gmail.com>
Co-authored-by: Kasper Fabricius Kristensen <45367945+kasperkristensen@users.noreply.github.com>

www/reference/data/storefront-api.json

@@ -0,0 +1 @@
+{"tags":{"Auth":[{"method":"POST","path":"/auth","operationId":"PostAuth","summary":"Authenticate Customer","description":"Logs a Customer in and authorizes them to view their details. Successful authentication will set a session cookie in the Customer's browser.","parameters":[],"tags":["Auth"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"properties":{"customer":{"$ref":"#/components/schemas/customer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","description":"The Customer's email."},"password":{"type":"string","description":"The Customer's password."}}}}}}},{"method":"DELETE","path":"/auth","operationId":"DeleteAuth","summary":"Log out","description":"Destroys a Customer's authenticated session.","tags":["Auth"],"responses":{"200":{"description":"OK"}}},{"method":"GET","path":"/auth","operationId":"GetAuth","summary":"Get Session","description":"Gets the currently logged in Customer.","tags":["Auth"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"properties":{"customer":{"$ref":"#/components/schemas/customer"}}}}}}}},{"method":"GET","path":"/auth/{email}","operationId":"GetAuthEmail","summary":"Check if email has account","description":"Checks if a Customer with the given email has signed up.","parameters":[{"in":"path","name":"email","required":true,"description":"The Customer's email.","schema":{"type":"string"}}],"tags":["Auth"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"properties":{"exists":{"type":"boolean"}}}}}}}}],"Cart":[{"method":"POST","path":"/carts/{id}/shipping-methods","operationId":"PostCartsCartShippingMethod","description":"Adds a Shipping Method to the Cart.","summary":"Add a Shipping Method","tags":["Cart"],"parameters":[{"in":"path","name":"id","required":true,"description":"The cart id.","schema":{"type":"string"}}],"responses":{"200":{"description":"A successful response","content":{"application/json":{"schema":{"properties":{"cart":{"$ref":"#/components/schemas/cart"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["option_id"],"properties":{"option_id":{"type":"string","description":"id of the shipping option to create the method from"},"data":{"type":"object","description":"Used to hold any data that the shipping method may need to process the fulfillment of the order. Look at the documentation for your installed fulfillment providers to find out what to send."}}}}}}},{"method":"POST","path":"/carts/{id}/complete-cart","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":{"oneOf":[{"type":"object","properties":{"order":{"$ref":"#/components/schemas/order"}}},{"type":"object","properties":{"cart":{"$ref":"#/components/schemas/cart"}}}]}}}}}},{"method":"POST","path":"/carts","summary":"Create a Cart","operationId":"PostCart","description":"Creates a Cart within the given region and with the initial items. If no `region_id` is provided the cart will be associated with the first Region available. If no items are provided the cart will be empty after creation. If a user is logged in the cart's customer id and email will be set.","requestBody":{"content":{"application/json":{"schema":{"properties":{"region_id":{"type":"string","description":"The id of the Region to create the Cart in."},"country_code":{"type":"string","description":"The 2 character ISO country code to create the Cart in."},"items":{"description":"An optional array of `variant_id`, `quantity` pairs to generate Line Items from.","type":"array","items":{"properties":{"variant_id":{"description":"The id of the Product Variant to generate a Line Item from.","type":"string"},"quantity":{"description":"The quantity of the Product Variant to add","type":"integer"}}}},"context":{"description":"An optional object to provide context to the Cart. The `context` field is automatically populated with `ip` and `user_agent`","type":"object"}}}}}},"tags":["Cart"],"responses":{"200":{"description":"Successfully created a Line truncated