docs: prep for v2 documentation (#6710)

This PR includes documentation that preps for v2 docs (but doesn't introduce new docs).

_Note: The number of file changes in the PR is due to find-and-replace within the `references` which is unavoidable. Let me know if I should move it to another PR._

## Changes

- Change Medusa version in base OAS used for v2.
- Fix to docblock generator related to not catching all path parameters.
- Added typedoc plugin that generates ER Diagrams, which will be used specifically for data model references in commerce modules.
- Changed OAS tool to output references in `www/apps/api-reference/specs-v2` directory when the `--v2` option is used.
- Added a version switcher to the API reference to switch between V1 and V2. This switcher is enabled by an environment variable, so it won't be visible/usable at the moment.
- Upgraded docusaurus to v3.0.1
- Added new Vale rules to ensure correct spelling of Medusa Admin and module names.
- Added new components to the `docs-ui` package that will be used in future documentation changes.

www/apps/api-reference/components/MDXComponents/index.tsx

@@ -2,7 +2,7 @@ import type { MDXComponents } from "mdx/types"
 import Security from "./Security"
 import type { OpenAPIV3 } from "openapi-types"
 import H2 from "./H2"
-import { CodeMdx, Kbd, NextLink } from "docs-ui"
+import { Link, MDXComponents as UiMDXComponents } from "docs-ui"
 
 export type ScopeType = {
   specs?: OpenAPIV3.Document
@@ -11,11 +11,12 @@ export type ScopeType = {
 
 const getCustomComponents = (scope?: ScopeType): MDXComponents => {
   return {
+    ...UiMDXComponents,
     Security: () => <Security specs={scope?.specs} />,
-    code: CodeMdx,
-    a: NextLink,
-    h2: (props) => <H2 addToSidebar={scope?.addToSidebar} {...props} />,
-    kbd: Kbd,
+    a: Link,
+    h2: (props: React.HTMLAttributes<HTMLHeadingElement>) => (
+      <H2 addToSidebar={scope?.addToSidebar} {...props} />
+    ),
   }
 }
 

www/apps/api-reference/components/MDXContent/Server/index.tsx

@@ -20,6 +20,9 @@ const MDXContentServer = ({ content, ...props }: MDXContentServerProps) => {
         components={getCustomComponents((props.scope as ScopeType) || {})}
         options={{
           scope: props.scope,
+          mdxOptions: {
+            development: process.env.NEXT_PUBLIC_ENV === "development",
+          },
         }}
         {...props}
       />

www/apps/api-reference/components/Navbar/index.tsx

@@ -1,47 +1,48 @@
 "use client"
 
-import { Navbar as UiNavbar, usePageLoading } from "docs-ui"
-import getLinkWithBasePath from "../../utils/get-link-with-base-path"
-import { useSidebar } from "docs-ui"
+import {
+  Navbar as UiNavbar,
+  getNavbarItems,
+  usePageLoading,
+  useSidebar,
+} from "docs-ui"
 import FeedbackModal from "./FeedbackModal"
+import { useMemo } from "react"
+import { config } from "../../config"
+import { usePathname } from "next/navigation"
+import VersionSwitcher from "../VersionSwitcher"
 
 const Navbar = () => {
   const { setMobileSidebarOpen, mobileSidebarOpen } = useSidebar()
+  const pathname = usePathname()
   const { isLoading } = usePageLoading()
 
+  const navbarItems = useMemo(
+    () =>
+      getNavbarItems({
+        basePath: config.baseUrl,
+        activePath: pathname,
+      }),
+    [pathname]
+  )
+
   return (
     <UiNavbar
       logo={{
         light: "/images/logo-icon.png",
         dark: "/images/logo-icon-dark.png",
       }}
-      items={[
-        {
-          href: `/`,
-          label: "Docs",
-        },
-        {
-          href: `/user-guide`,
-          label: "User Guide",
-        },
-        {
-          href: `${getLinkWithBasePath("/store")}`,
-          label: "Store API",
-        },
-        {
-          href: `${getLinkWithBasePath("/admin")}`,
-          label: "Admin API",
-        },
-        {
-          href: `/ui`,
-          label: "UI",
-        },
-      ]}
+      items={navbarItems}
       mobileMenuButton={{
         setMobileSidebarOpen,
         mobileSidebarOpen,
       }}
-      additionalActions={<FeedbackModal />}
+      additionalActionsBefore={
+        <>
+          {process.env.NEXT_PUBLIC_VERSIONING === "true" && <VersionSwitcher />}
+        </>
+      }
+      additionalActionsAfter={<FeedbackModal />}
       isLoading={isLoading}
     />
   )

www/apps/api-reference/components/PageHeading/index.tsx

@@ -0,0 +1,25 @@
+"use client"
+
+import { capitalize } from "docs-ui"
+import { useArea } from "../../providers/area"
+import { useVersion } from "../../providers/version"
+
+type PageHeadingProps = {
+  className?: string
+}
+
+const PageHeading = ({ className }: PageHeadingProps) => {
+  const { area } = useArea()
+  const { version } = useVersion()
+
+  const versionText =
+    process.env.NEXT_PUBLIC_VERSIONING === "true" ? ` V${version}` : ""
+
+  return (
+    <h1 className={className}>
+      Medusa{versionText} {capitalize(area)} API Reference
+    </h1>
+  )
+}
+
+export default PageHeading

www/apps/api-reference/components/Tags/Operation/CodeSection/RequestSamples/index.tsx

@@ -1,5 +1,5 @@
 import type { Code } from "@/types/openapi"
-import { CodeTabs } from "docs-ui"
+import { LegacyCodeTabs } from "docs-ui"
 import slugify from "slugify"
 
 export type TagOperationCodeSectionRequestSamplesProps = {
@@ -12,7 +12,7 @@ const TagOperationCodeSectionRequestSamples = ({
   return (
     <div>
       <h3>Request samples</h3>
-      <CodeTabs
+      <LegacyCodeTabs
         tabs={codeSamples.map((codeSample) => ({
           label: codeSample.label,
           value: slugify(codeSample.label),

www/apps/api-reference/components/Tags/Operation/DescriptionSection/index.tsx

@@ -8,7 +8,7 @@ import dynamic from "next/dynamic"
 import TagsOperationDescriptionSectionParameters from "./Parameters"
 import MDXContentClient from "@/components/MDXContent/Client"
 import { useArea } from "../../../../providers/area"
-import { Feedback, Badge, NextLink, FeatureFlagNotice } from "docs-ui"
+import { Feedback, Badge, Link, FeatureFlagNotice } from "docs-ui"
 import { usePathname } from "next/navigation"
 import formatReportLink from "../../../../utils/format-report-link"
 
@@ -70,9 +70,9 @@ const TagsOperationDescriptionSection = ({
       {operation.externalDocs && (
         <>
           Related guide:{" "}
-          <NextLink href={operation.externalDocs.url} target="_blank">
+          <Link href={operation.externalDocs.url} target="_blank">
             {operation.externalDocs.description || "Read More"}
-          </NextLink>
+          </Link>
         </>
       )}
       {operation.security && (

www/apps/api-reference/components/Tags/Operation/FeatureFlagNotice/index.tsx

@@ -1,4 +1,4 @@
-import { Badge, NextLink, Tooltip } from "docs-ui"
+import { Badge, Link, Tooltip } from "docs-ui"
 
 export type TagsOperationFeatureFlagNoticeProps = {
   featureFlag: string
@@ -19,12 +19,12 @@ const TagsOperationFeatureFlagNotice = ({
         <span className={tooltipTextClassName}>
           To use this {type}, make sure to
           <br />
-          <NextLink
+          <Link
             href="https://docs.medusajs.com/development/feature-flags/toggle"
             target="__blank"
           >
             enable its feature flag: <code>{featureFlag}</code>
-          </NextLink>
+          </Link>
         </span>
       }
       clickable

www/apps/api-reference/components/Tags/Operation/Parameters/Description/index.tsx

@@ -3,7 +3,7 @@ import type { SchemaObject } from "@/types/openapi"
 import clsx from "clsx"
 import dynamic from "next/dynamic"
 import { Fragment } from "react"
-import { NextLink, type InlineCodeProps, capitalize } from "docs-ui"
+import { Link, type InlineCodeProps, capitalize } from "docs-ui"
 
 const InlineCode = dynamic<InlineCodeProps>(
   async () => (await import("docs-ui")).InlineCode
@@ -122,9 +122,9 @@ const TagOperationParametersDescription = ({
       {schema.externalDocs && (
         <>
           Related guide:{" "}
-          <NextLink href={schema.externalDocs.url} target="_blank">
+          <Link href={schema.externalDocs.url} target="_blank">
             {schema.externalDocs.description || "Read More"}
-          </NextLink>
+          </Link>
         </>
       )}
     </div>

www/apps/api-reference/components/Tags/Operation/Parameters/Name/index.tsx

@@ -1,11 +1,5 @@
 import type { SchemaObject } from "@/types/openapi"
-import dynamic from "next/dynamic"
-import type { TooltipProps } from "docs-ui"
-import { Badge, ExpandableNotice, FeatureFlagNotice, NextLink } from "docs-ui"
-
-const Tooltip = dynamic<TooltipProps>(
-  async () => (await import("docs-ui")).Tooltip
-) as React.FC<TooltipProps>
+import { Badge, ExpandableNotice, FeatureFlagNotice } from "docs-ui"
 
 export type TagOperationParametersNameProps = {
   name: string
@@ -37,7 +31,7 @@ const TagOperationParametersName = ({
           <br />
           <FeatureFlagNotice
             featureFlag={schema["x-featureFlag"]}
-            type="parameter"
+            type="type"
           />
         </>
       )}

www/apps/api-reference/components/Tags/Paths/index.tsx

@@ -4,22 +4,18 @@ import getSectionId from "@/utils/get-section-id"
 import type { OpenAPIV3 } from "openapi-types"
 import useSWR from "swr"
 import type { Operation, PathsObject } from "@/types/openapi"
-import {
-  SidebarItemSections,
-  useSidebar,
-  type SidebarItemType,
-  swrFetcher,
-} from "docs-ui"
+import { useSidebar, swrFetcher, getLinkWithBasePath } from "docs-ui"
 import { Fragment, useEffect, useMemo } from "react"
 import dynamic from "next/dynamic"
 import type { TagOperationProps } from "../Operation"
 import { useArea } from "@/providers/area"
-import getLinkWithBasePath from "@/utils/get-link-with-base-path"
 import clsx from "clsx"
 import { useBaseSpecs } from "@/providers/base-specs"
 import getTagChildSidebarItems from "@/utils/get-tag-child-sidebar-items"
 import { useLoading } from "@/providers/loading"
 import DividedLoading from "@/components/DividedLoading"
+import { SidebarItemSections, SidebarItemType } from "types"
+import { useVersion } from "../../../providers/version"
 
 const TagOperation = dynamic<TagOperationProps>(
   async () => import("../Operation")
@@ -32,6 +28,7 @@ export type TagPathsProps = {
 const TagPaths = ({ tag, className }: TagPathsProps) => {
   const tagSlugName = useMemo(() => getSectionId([tag.name]), [tag])
   const { area } = useArea()
+  const { version } = useVersion()
   const { items, addItems, findItemInSection } = useSidebar()
   const { baseSpecs } = useBaseSpecs()
   const { loading } = useLoading()
@@ -47,7 +44,10 @@ const TagPaths = ({ tag, className }: TagPathsProps) => {
     paths: PathsObject
   }>(
     !Object.keys(paths).length
-      ? getLinkWithBasePath(`/tag?tagName=${tagSlugName}&area=${area}`)
+      ? getLinkWithBasePath(
+          `/tag?tagName=${tagSlugName}&area=${area}&version=${version}`,
+          process.env.NEXT_PUBLIC_BASE_PATH
+        )
       : null,
     swrFetcher,
     {

www/apps/api-reference/components/Tags/Section/index.tsx

@@ -15,7 +15,7 @@ import SectionContainer from "../../Section/Container"
 import { useArea } from "../../../providers/area"
 import SectionDivider from "../../Section/Divider"
 import clsx from "clsx"
-import { Feedback, Loading, NextLink } from "docs-ui"
+import { Feedback, Loading, Link } from "docs-ui"
 import { usePathname } from "next/navigation"
 import formatReportLink from "../../../utils/format-report-link"
 
@@ -100,9 +100,9 @@ const TagSection = ({ tag }: TagSectionProps) => {
             {tag.externalDocs && (
               <>
                 Related guide:{" "}
-                <NextLink href={tag.externalDocs.url} target="_blank">
+                <Link href={tag.externalDocs.url} target="_blank">
                   {tag.externalDocs.description || "Read More"}
-                </NextLink>
+                </Link>
               </>
             )}
             <Feedback

www/apps/api-reference/components/Tags/index.tsx

@@ -7,11 +7,12 @@ import { useBaseSpecs } from "@/providers/base-specs"
 import dynamic from "next/dynamic"
 import type { TagSectionProps } from "./Section"
 import { useArea } from "@/providers/area"
-import getLinkWithBasePath from "@/utils/get-link-with-base-path"
-import { SidebarItemSections, swrFetcher, useSidebar } from "docs-ui"
+import { swrFetcher, useSidebar, getLinkWithBasePath } from "docs-ui"
 import getSectionId from "@/utils/get-section-id"
 import { ExpandedDocument } from "@/types/openapi"
 import getTagChildSidebarItems from "@/utils/get-tag-child-sidebar-items"
+import { SidebarItemSections } from "types"
+import { useVersion } from "../../providers/version"
 
 const TagSection = dynamic<TagSectionProps>(
   async () => import("./Section")
@@ -32,10 +33,14 @@ const Tags = () => {
   const { baseSpecs, setBaseSpecs } = useBaseSpecs()
   const { addItems } = useSidebar()
   const { area } = useArea()
+  const { version } = useVersion()
 
   const { data } = useSWR<ExpandedDocument>(
     loadData && !baseSpecs
-      ? getLinkWithBasePath(`/base-specs?area=${area}&expand=${expand}`)
+      ? getLinkWithBasePath(
+          `/base-specs?area=${area}&expand=${expand}&version=${version}`,
+          process.env.NEXT_PUBLIC_BASE_PATH
+        )
       : null,
     swrFetcher,
     {

www/apps/api-reference/components/VersionNote/index.tsx

@@ -0,0 +1,22 @@
+"use client"
+
+import { Note } from "docs-ui"
+import { useVersion } from "../../providers/version"
+
+const VersionNote = () => {
+  const { version } = useVersion()
+
+  return (
+    <>
+      {version === "2" && (
+        <Note type="warning" title="Production Warning">
+          Medusa v2.0 is in development and not suitable for production
+          environments. As such, the API reference is incomplete and subject to
+          change, so please use it with caution.
+        </Note>
+      )}
+    </>
+  )
+}
+
+export default VersionNote

www/apps/api-reference/components/VersionSwitcher/index.tsx

@@ -0,0 +1,36 @@
+"use client"
+
+import { Toggle } from "docs-ui"
+import { useVersion } from "../../providers/version"
+import clsx from "clsx"
+
+const VersionSwitcher = () => {
+  const { version, changeVersion } = useVersion()
+
+  return (
+    <div className="flex gap-0.5 justify-center items-center">
+      <span
+        className={clsx(
+          version === "1" && "text-medusa-fg-subtle",
+          version === "2" && "text-medusa-fg-disabled"
+        )}
+      >
+        V1
+      </span>
+      <Toggle
+        checked={version === "2"}
+        onCheckedChange={(checked) => changeVersion(checked ? "2" : "1")}
+      />
+      <span
+        className={clsx(
+          version === "1" && "text-medusa-fg-disabled",
+          version === "2" && "text-medusa-fg-subtle"
+        )}
+      >
+        V2
+      </span>
+    </div>
+  )
+}
+
+export default VersionSwitcher