docs: prep for v2 documentation (medusajs#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.

.changeset/sixty-kids-divide.md

@@ -0,0 +1,5 @@
+---
+"@medusajs/oas-github-ci": patch
+---
+
+feat(oas-github-ci): output specs into `specs-v2` directory when the `--v2` option is passed

.vale.ini

@@ -12,6 +12,7 @@ write-good.E-Prime=No
 write-good.So=No
 write-good.ThereIs=No
 Vale.Terms=No
+BlockIgnores={/\* [\s\S]+ \*/}
 
 [formats]
 mdx = md

docs-util/oas-output/base-v2/admin.oas.base.yaml

@@ -1,6 +1,6 @@
 openapi: 3.0.0
 info:
-  version: 1.0.0
+  version: 2.0.0
   title: Medusa Admin API
   license:
     name: MIT

docs-util/oas-output/base-v2/store.oas.base.yaml

@@ -1,6 +1,6 @@
 openapi: 3.0.0
 info:
-  version: 1.0.0
+  version: 2.0.0
   title: Medusa Storefront API
   license:
     name: MIT

docs-util/packages/docblock-generator/src/classes/kinds/oas.ts

@@ -28,7 +28,7 @@ import OasSchemaHelper from "../helpers/oas-schema.js"
 import formatOas from "../../utils/format-oas.js"
 import { DEFAULT_OAS_RESPONSES } from "../../constants.js"
 
-export const API_ROUTE_PARAM_REGEX = /\[(.+)\]/g
+export const API_ROUTE_PARAM_REGEX = /\[(.+?)\]/g
 const RES_STATUS_REGEX = /^res[\s\S]*\.status\((\d+)\)/
 
 type SchemaDescriptionOptions = {
@@ -112,9 +112,12 @@ class OasKindGenerator extends FunctionKindGenerator {
     // and the second of type `MedusaResponse`
     return (
       (functionNode.parameters.length === 2 &&
-        functionNode.parameters[0].type
+        (functionNode.parameters[0].type
           ?.getText()
-          .startsWith("MedusaRequest") &&
+          .startsWith("MedusaRequest") ||
+          functionNode.parameters[0].type
+            ?.getText()
+            .startsWith("AuthenticatedMedusaRequest")) &&
         functionNode.parameters[1].type
           ?.getText()
           .startsWith("MedusaResponse")) ||
@@ -988,26 +991,32 @@ class OasKindGenerator extends FunctionKindGenerator {
      */
     tagName?: string
   }): OpenAPIV3.ParameterObject[] {
-    const pathParameters = API_ROUTE_PARAM_REGEX.exec(oasPath)?.slice(1)
+    // reset regex manually
+    API_ROUTE_PARAM_REGEX.lastIndex = 0
+    let pathParameters: string[] | undefined
     const parameters: OpenAPIV3.ParameterObject[] = []
-
-    if (pathParameters?.length) {
-      pathParameters.forEach((parameter) =>
-        parameters.push(
-          this.getParameterObject({
-            type: "path",
-            name: parameter,
-            description: this.getSchemaDescription({
-              typeStr: parameter,
-              parentName: tagName,
-            }),
-            required: true,
-            schema: {
-              type: "string",
-            },
-          })
+    while (
+      (pathParameters = API_ROUTE_PARAM_REGEX.exec(oasPath)?.slice(1)) !==
+      undefined
+    ) {
+      if (pathParameters.length) {
+        pathParameters.forEach((parameter) =>
+          parameters.push(
+            this.getParameterObject({
+              type: "path",
+              name: parameter,
+              description: this.getSchemaDescription({
+                typeStr: parameter,
+                parentName: tagName,
+              }),
+              required: true,
+              schema: {
+                type: "string",
+              },
+            })
+          )
         )
-      )
+      }
     }
 
     return parameters

docs-util/packages/typedoc-config/_merger.js

@@ -71,10 +71,8 @@ module.exports = {
       showCommentsAsHeader: true,
       sections: baseSectionsOptions,
       parameterStyle: "component",
-      parameterComponent: "ParameterTypes",
-      mdxImports: [
-        `import ParameterTypes from "@site/src/components/ParameterTypes"`,
-      ],
+      parameterComponent: "TypeList",
+      mdxImports: [`import TypeList from "@site/src/components/TypeList"`],
     },
     internal: {
       maxLevel: 1,
@@ -231,7 +229,7 @@ npx medusa develop
       reflectionTitle: {
         kind: false,
         typeParameters: false,
-        suffix: " Reference",
+        suffix: "Reference",
       },
     },
 
@@ -638,7 +636,7 @@ npx medusa develop
       reflectionTitle: {
         kind: false,
         typeParameters: false,
-        suffix: " Reference",
+        suffix: "Reference",
       },
     },
 
@@ -681,7 +679,7 @@ npx medusa develop
       reflectionTitle: {
         kind: false,
         typeParameters: false,
-        suffix: " Reference",
+        suffix: "Reference",
       },
     },
 
@@ -780,7 +778,7 @@ npx medusa develop
       reflectionTitle: {
         kind: false,
         typeParameters: false,
-        suffix: " Reference",
+        suffix: "Reference",
       },
     },
 

docs-util/packages/typedoc-plugin-custom/src/index.ts

@@ -5,6 +5,7 @@ import { load as parseOasSchemaPlugin } from "./parse-oas-schema-plugin"
 import { load as apiIgnorePlugin } from "./api-ignore"
 import { load as eslintExamplePlugin } from "./eslint-example"
 import { load as signatureModifierPlugin } from "./signature-modifier"
+import { MermaidDiagramGenerator } from "./mermaid-diagram-generator"
 import { load as parentIgnorePlugin } from "./parent-ignore"
 import { GenerateNamespacePlugin } from "./generate-namespace"
 
@@ -18,4 +19,5 @@ export function load(app: Application) {
   parentIgnorePlugin(app)
 
   new GenerateNamespacePlugin(app)
+  new MermaidDiagramGenerator(app)
 }