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

www/docs/docusaurus.config.js

@@ -1,5 +1,6 @@
 const path = require("path")
 const docsPath = path.join(__dirname, "../../docs/content")
+const apisPath = path.join(__dirname, "../../docs/api")
 
 const algoliaAppId = process.env.ALGOLIA_APP_ID || "temp"
 const algoliaApiKey = process.env.ALGOLIA_API_KEY || "temp"
@@ -65,13 +66,32 @@ module.exports = {
         },
         {
           type: 'dropdown',
-          label: 'References',
+          label: 'REST API Reference',
           items: [
             {
-              href: `https://docs.medusajs.com/api/store`,
-              target: "_self",
-              label: "API Reference",
+              type: 'html',
+              value: `
+              <a href="/api/store" target="_blank" rel="noopener noreferrer" class="dropdown__link">Store
+                <svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_node_modules-@docusaurus-theme-classic-lib-theme-Icon-ExternalLink-styles-module">
+                  <path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path>
+                </svg>
+              </a>`
             },
+            {
+              type: 'html',
+              value: `
+              <a href="/api/admin" target="_blank" rel="noopener noreferrer" class="dropdown__link">Admin
+                <svg width="12" height="12" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_node_modules-@docusaurus-theme-classic-lib-theme-Icon-ExternalLink-styles-module">
+                  <path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path>
+                </svg>
+              </a>`
+            },
+          ],
+        },
+        {
+          type: 'dropdown',
+          label: 'References',
+          items: [
             {
               to: "cli/reference",
               label: "CLI Reference",
@@ -158,9 +178,45 @@ module.exports = {
           showLastUpdateTime: true
         },
         theme: {
-          customCss: require.resolve("./src/css/custom.css"),
+          customCss: require.resolve("./src/css/custom.css")
         },
       },
     ],
+    [
+      'redocusaurus',
+      {
+        // Plugin Options for loading OpenAPI files
+        specs: [
+          {
+            spec: path.join(apisPath, 'store/openapi.yaml'),
+            route: '/api/store',
+            layout: {
+              noFooter: true
+            }
+          },
+          {
+            spec: path.join(apisPath, 'admin/openapi.yaml'),
+            route: '/api/admin',
+            layout: {
+              noFooter: true
+            }
+          }
+        ],
+        // Theme Options for modifying how redoc renders them
+        theme: {
+          primaryColorDark: '#242526',
+          options: {
+            disableSearch: true,
+            nativeScrollbars: true,
+            sortTagsAlphabetically: true,
+            hideDownloadButton: true,
+            expandResponses: "200,204",
+            generatedPayloadSamplesMaxDepth: 4,
+            showObjectSchemaExamples: true,
+            requiredPropsFirst: true
+          }
+        }
+      },
+    ],
   ],
 }

www/docs/package.json

@@ -30,6 +30,7 @@
     "prism-react-renderer": "^1.3.1",
     "react": "^17.0.1",
     "react-dom": "^17.0.1",
+    "redocusaurus": "^1.3.0",
     "url-loader": "^4.1.1"
   },
   "browserslist": {

www/docs/src/components/Banner/Banner.js

@@ -1,56 +0,0 @@
-import React, { useEffect, useState } from "react"
-
-import CloseIcon from "../close-icon"
-import ConfLogo from "../../../static/img/logo.svg"
-import clsx from "clsx"
-import styles from "./banner.module.css"
-import {useColorMode} from '@docusaurus/theme-common';
-
-const Banner = (props) => {
-  const [isBannerVisible, setIsBannerVisible] = useState(true)
-  const { isDarkTheme } = useColorMode()
-
-  const handleDismissBanner = () => {
-    setIsBannerVisible(false)
-    if (localStorage) {
-      localStorage.setItem("mc::banner", false)
-    }
-  }
-
-  useEffect(() => {
-    if (localStorage) {
-      const shouldShow = localStorage.getItem("mc::banner")
-      if (!shouldShow) {
-        setIsBannerVisible(true)
-      }
-
-      if (shouldShow === "false") {
-        setIsBannerVisible(false)
-      }
-    }
-  }, [])
-
-  return (
-    isBannerVisible && (
-      <div className={clsx(styles.bannerContainer, "margin-top--lg")}>
-        <div
-          className={clsx(styles.banner, "padding--sm", "padding-right--md")}
-        >
-          <div className="padding" sx={{ marginLeft: "10px" }}>
-            <ConfLogo />
-            <p className="padding-left--md">
-              We are still working on building out our documentation and guides,
-              but if you are interested in learning more please reach out - we
-              would love to jump on a call with you and help you get set up!
-            </p>
-          </div>
-          {/* <div style={{ cursor: "pointer" }} onClick={handleDismissBanner}>
-            <CloseIcon fill={isDarkTheme ? "white" : "black"} />
-          </div> */}
-        </div>
-      </div>
-    )
-  )
-}
-
-export default Banner

www/docs/src/components/Banner/banner.module.css

@@ -1,18 +0,0 @@
-.bannerContainer {
-  height: 100%;
-  padding: 10px 0px;
-  margin-bottom: 20px;
-  background-color: var(--ifm-medusa-gray);
-  border-radius: 5px;
-}
-
-.bannerContainer svg {
-  max-width: 100px;
-  margin-left: 15px;
-}
-
-.banner {
-  display: flex;
-  flex-direction: row;
-  justify-content: space-between;
-}

www/docs/src/components/Banner/index.js

@@ -1 +0,0 @@
-export { default as Banner } from "./Banner"

www/docs/src/components/Layout/Layout.js

@@ -1,4 +1,5 @@
-import React from "react"
+import React, { useEffect } from "react"
+
 import RootLayout from "@theme/Layout"
 
 const Layout = ({ children, ...props }) => {

www/docs/src/components/Tabs/tabs.module.css

@@ -11,5 +11,4 @@
   color: var(--ifm-color-primary);
   border-bottom: 3px solid var(--ifm-color-primary) !important;
   font-weight: 500;
-  transition: ;
 }

www/docs/src/css/custom.css

@@ -284,7 +284,7 @@ details summary {
   cursor: pointer;
 }
 
-.theme-doc-markdown a:not(.box-link):hover {
+[data-theme="dark"] .theme-doc-markdown a.card:hover {
   color: rgba(255, 255, 255, 0.8);
   text-decoration: none;
 }
@@ -317,4 +317,13 @@ details summary {
   max-width: 100%;
   word-break: break-word;
   white-space: break-spaces;
+}
+
+/* API Reference Styling */
+html[data-theme="dark"] .redocusaurus .expanded + tr > td > div {
+  background-color: var(--ifm-medusa-gray);
+}
+
+.redocusaurus a {
+  color: var(--ifm-link-color) !important;
 }

www/docs/src/theme/DocCard/index.js

@@ -9,6 +9,7 @@ import clsx from 'clsx';
 import isInternalUrl from '@docusaurus/isInternalUrl';
 import styles from './styles.module.css';
 import {translate} from '@docusaurus/Translate';
+
 function CardContainer({href, children}) {
   return (
     <Link

www/docs/src/theme/Redoc/index.js

@@ -0,0 +1,62 @@
+import React, { useEffect, useState } from 'react';
+
+import Redoc from '@theme-original/Redoc';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+
+export default function RedocWrapper(props) {
+
+  const isBrowser = useIsBrowser();
+  const [loading, setLoading] = useState(isBrowser ? document.readyState !== 'complete' : true)
+  
+  useEffect(() => {
+    if (isBrowser) {
+
+      //redocusaurus in dark mode displays styling wrong
+      //until the issue is resolved, this is a work around to hide
+      //the bad styling
+      window.onload = function () {
+        setLoading(false);
+      }
+
+      //fallback in case the onload function does not execute
+      setTimeout(() => {
+        if (loading) {
+          setLoading(false);
+        }
+      }, 1000)
+      
+      function scrollHandler () {
+        const redocSidebar = document.querySelector('.redocusaurus .menu-content');
+        const navbar = document.querySelector('.navbar');
+        if (!redocSidebar || !navbar) {
+          return;
+        }
+  
+        let offset = navbar.clientHeight;
+        for (let [_, className] of navbar.classList.entries()) {
+          if (className.indexOf('navbarHidden') !== -1) {
+            offset = 0;
+            break;
+          }
+        }
+        
+        redocSidebar.style.top = `${offset}px`
+      }
+  
+      window.addEventListener('scroll', scrollHandler);
+  
+      return () => {
+        window.removeEventListener('scroll', scrollHandler);
+      }
+    }
+  }, [isBrowser])
+  
+  return (
+    <div style={{
+      opacity: loading ? 0 : 1,
+      transition: 'opacity 0.2s'
+    }}>
+      <Redoc {...props} />
+    </div>
+  );
+}

www/docs/src/theme/SearchPage/index.js

@@ -22,6 +22,7 @@ import clsx from 'clsx';
 import styles from './styles.module.css';
 import {useAllDocsData} from '@docusaurus/plugin-content-docs/client';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+
 // Very simple pluralization: probably good enough for now
 function useDocumentsFoundPlural() {
   const {selectMessage} = usePluralForm();