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

docs/api/store-spec3-base.json

@@ -3,70 +3,76 @@
   "info": {
     "version": "1.0.0",
     "title": "Medusa Storefront API",
+    "description": "API reference for Medusa's Storefront endpoints. All endpoints are prefixed with `/store`.",
     "license": {
-      "name": "MIT"
+      "name": "MIT",
+      "url": "https://github.com/medusajs/medusa/blob/master/LICENSE"
     }
   },
   "tags": [
     {
       "name": "Auth",
-      "description": "Auth endpoints allows authorization of admin Users and manages their sessions."
+      "description": "Auth endpoints that allow authorization of customers and manages their sessions."
     },
     {
       "name": "Cart",
+      "description": "Cart endpoints that allow handling carts in Medusa.",
       "x-resourceId": "cart"
     },
     {
       "name": "Collection",
+      "description": "Collection endpoints that allow handling collections in Medusa.",
       "x-resourceId": "product_collection"
     },
     {
       "name": "Customer",
+      "description": "Customer endpoints that allow handling customers in Medusa.",
       "x-resourceId": "customer"
     },
-    {
-      "name": "Discount",
-      "x-resourceId": "discount"
-    },
     {
       "name": "Gift Card",
+      "description": "Gift Card endpoints that allow handling gift cards in Medusa.",
       "x-resourceId": "gift_card"
     },
-    {
-      "name": "Notification",
-      "x-resourceId": "notification"
-    },
     {
       "name": "Order",
+      "description": "Order endpoints that allow handling orders in Medusa.",
       "x-resourceId": "order"
     },
     {
       "name": "Product",
+      "description": "Product endpoints that allow handling products in Medusa.",
       "x-resourceId": "product"
     },
+    {
+      "name": "Product Variant",
+      "description": "Product Variant endpoints that allow handling product variants in Medusa.",
+      "x-resourceId": "product_variant"
+    },
     {
       "name": "Region",
+      "description": "Region endpoints that allow handling regions in Medusa.",
       "x-resourceId": "region"
     },
+    {
+      "name": "Return Reason",
+      "description": "Return Reason endpoints that allow handling return reasons in Medusa.",
+      "x-resourceId": "return_reason"
+    },
     {
       "name": "Return",
+      "description": "Return endpoints that allow handling returns in Medusa.",
       "x-resourceId": "return"
     },
     {
       "name": "Shipping Option",
+      "description": "Shipping Option endpoints that allow handling shipping options in Medusa.",
       "x-resourceId": "shipping_option"
     },
-    {
-      "name": "Shipping Profile",
-      "x-resourceId": "shipping_profile"
-    },
     {
       "name": "Swap",
+      "description": "Swap endpoints that allow handling swaps in Medusa.",
       "x-resourceId": "swap"
-    },
-    {
-      "name": "Product Variant",
-      "x-resourceId": "product_variant"
     }
   ],
   "servers": [