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/utils/get-base-url.ts

@@ -1,3 +0,0 @@
-export default function getBaseUrl() {
-  return process.env.NEXT_PUBLIC_BASE_URL || "http://localhost:3000"
-}

www/apps/api-reference/utils/get-link-with-base-path.ts

@@ -1,3 +0,0 @@
-export default function getLinkWithBasePath(path: string): string {
-  return `${process.env.NEXT_PUBLIC_BASE_PATH || "/api"}${path}`
-}

www/apps/api-reference/utils/get-paths-of-tag.ts

@@ -1,7 +1,7 @@
 import path from "path"
 import { promises as fs } from "fs"
 import type { OpenAPIV3 } from "openapi-types"
-import type { Operation, Document } from "@/types/openapi"
+import type { Operation, Document, Version } from "@/types/openapi"
 import readSpecDocument from "./read-spec-document"
 import getSectionId from "./get-section-id"
 import OpenAPIParser from "@readme/openapi-parser"
@@ -12,10 +12,15 @@ type ParsedPathItemObject = OpenAPIV3.PathItemObject<Operation> & {
 
 export default async function getPathsOfTag(
   tagName: string,
-  area: string
+  area: string,
+  version: Version = "1"
 ): Promise<Document> {
   // get path files
-  const basePath = path.join(process.cwd(), `specs/${area}/paths`)
+  const basePath = path.join(
+    process.cwd(),
+    version === "1" ? "specs" : "specs-v2",
+    `${area}/paths`
+  )
 
   const files = await fs.readdir(basePath)
 

www/apps/api-reference/utils/get-tag-child-sidebar-items.tsx

@@ -1,4 +1,4 @@
-import type { SidebarItemType } from "docs-ui"
+import type { SidebarItemType } from "types"
 import type { Operation, PathsObject } from "@/types/openapi"
 import type { OpenAPIV3 } from "openapi-types"
 import dynamic from "next/dynamic"

www/apps/api-reference/utils/get-url.ts

@@ -1,5 +1,5 @@
-import getBaseUrl from "./get-base-url"
+import { config } from "../config"
 
 export default function getUrl(area: string, tagName?: string): string {
-  return `${getBaseUrl()}/api/${area}#${tagName}`
+  return `${config.baseUrl}/api/${area}#${tagName}`
 }