docs: improvements and fixes to components in API reference (medusajs…

…#9410)

- Change layout of parameters for clearer display
- Fix schema code blocks being longer than container
- switch between showing required to showing optional indicator
- Fixed code tabs not having copy / report buttons

Closes DOCS-936

Preview: https://api-reference-v2-git-docs-api-ref-comp-improv-medusajs.vercel.app/v2/api/store

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

@@ -67,6 +67,14 @@ const TagsOperationDescriptionSection = ({
           workflow={operation["x-workflow"]}
         />
       )}
+      {operation.externalDocs && (
+        <>
+          Related guide:{" "}
+          <Link href={operation.externalDocs.url} target="_blank">
+            {operation.externalDocs.description || "Read More"}
+          </Link>
+        </>
+      )}
       <Feedback
         event="survey_api-ref"
         extraData={{
@@ -79,14 +87,6 @@ const TagsOperationDescriptionSection = ({
         vertical={true}
         question="Did this API Route run successfully?"
       />
-      {operation.externalDocs && (
-        <>
-          Related guide:{" "}
-          <Link href={operation.externalDocs.url} target="_blank">
-            {operation.externalDocs.description || "Read More"}
-          </Link>
-        </>
-      )}
       {operation.security && (
         <TagsOperationDescriptionSectionSecurity
           security={operation.security}

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

@@ -16,100 +16,37 @@ type TagOperationParametersDescriptionProps = {
 const TagOperationParametersDescription = ({
   schema,
 }: TagOperationParametersDescriptionProps) => {
-  let typeDescription: React.ReactNode = <></>
-  switch (true) {
-    case schema.type === "object":
-      typeDescription = (
-        <>
-          {schema.type} {schema.title ? `(${schema.title})` : ""}
-          {schema.nullable ? ` or null` : ""}
-        </>
-      )
-      break
-    case schema.type === "array":
-      typeDescription = (
-        <>
-          {schema.type === "array" && formatArrayDescription(schema.items)}
-          {schema.nullable ? ` or null` : ""}
-        </>
-      )
-      break
-    case schema.anyOf !== undefined:
-    case schema.allOf !== undefined:
-      typeDescription = (
-        <>
-          {formatUnionDescription(schema.allOf)}
-          {schema.nullable ? ` or null` : ""}
-        </>
-      )
-      break
-    case schema.oneOf !== undefined:
-      typeDescription = (
-        <>
-          {schema.oneOf?.map((item, index) => (
-            <Fragment key={index}>
-              {index !== 0 && <> or </>}
-              {item.type !== "array" && <>{item.title || item.type}</>}
-              {item.type === "array" && (
-                <>array{item.items.type ? ` of ${item.items.type}s` : ""}</>
-              )}
-            </Fragment>
-          ))}
-          {schema.nullable ? ` or null` : ""}
-        </>
-      )
-      break
-    default:
-      typeDescription = (
-        <>
-          {!schema.type ? "any" : schema.type}
-          {schema.nullable ? ` or null` : ""}
-          {schema.format ? ` <${schema.format}>` : ""}
-        </>
-      )
-  }
   return (
-    <div className={clsx("w-2/3 break-words pb-0.5")}>
-      {typeDescription}
+    <div className={clsx("pb-0.5 flex flex-col gap-0.25")}>
       {schema.default !== undefined && (
-        <>
-          <br />
-          <span>
-            Default:{" "}
-            <InlineCode className="break-words">
-              {JSON.stringify(schema.default)}
-            </InlineCode>
-          </span>
-        </>
+        <span>
+          Default:{" "}
+          <InlineCode className="break-words">
+            {JSON.stringify(schema.default)}
+          </InlineCode>
+        </span>
       )}
       {schema.enum && (
-        <>
-          <br />
-          <span>
-            Enum:{" "}
-            {schema.enum.map((value, index) => (
-              <Fragment key={index}>
-                {index !== 0 && <>, </>}
-                <InlineCode key={index}>{JSON.stringify(value)}</InlineCode>
-              </Fragment>
-            ))}
-          </span>
-        </>
+        <span>
+          Enum:{" "}
+          {schema.enum.map((value, index) => (
+            <Fragment key={index}>
+              {index !== 0 && <>, </>}
+              <InlineCode key={index}>{JSON.stringify(value)}</InlineCode>
+            </Fragment>
+          ))}
+        </span>
       )}
       {schema.example !== undefined && (
-        <>
-          <br />
-          <span>
-            Example:{" "}
-            <InlineCode className="break-words">
-              {JSON.stringify(schema.example)}
-            </InlineCode>
-          </span>
-        </>
+        <span>
+          Example:{" "}
+          <InlineCode className="break-words">
+            {JSON.stringify(schema.example)}
+          </InlineCode>
+        </span>
       )}
       {schema.description && (
         <>
-          <br />
           <MDXContentClient
             content={capitalize(schema.description)}
             className={clsx("!mb-0 [&>*]:!mb-0")}
@@ -120,33 +57,15 @@ const TagOperationParametersDescription = ({
         </>
       )}
       {schema.externalDocs && (
-        <>
+        <span>
           Related guide:{" "}
           <Link href={schema.externalDocs.url} target="_blank">
             {schema.externalDocs.description || "Read More"}
           </Link>
-        </>
+        </span>
       )}
     </div>
   )
 }
 
 export default TagOperationParametersDescription
-
-function formatArrayDescription(schema?: SchemaObject) {
-  if (!schema) {
-    return "Array"
-  }
-
-  const type =
-    schema.type === "object"
-      ? `objects ${schema.title ? `(${schema.title})` : ""}`
-      : `${schema.type || "object"}s`
-
-  return `Array of ${type}`
-}
-
-function formatUnionDescription(arr?: SchemaObject[]) {
-  const types = [...new Set(arr?.map((type) => type.type || "object"))]
-  return <>{types.join(" or ")}</>
-}

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

@@ -1,5 +1,6 @@
 import type { SchemaObject } from "@/types/openapi"
 import { Badge, ExpandableNotice, FeatureFlagNotice } from "docs-ui"
+import { Fragment } from "react"
 
 export type TagOperationParametersNameProps = {
   name: string
@@ -12,39 +13,101 @@ const TagOperationParametersName = ({
   isRequired,
   schema,
 }: TagOperationParametersNameProps) => {
+  let typeDescription: React.ReactNode = <></>
+  switch (true) {
+    case schema.type === "object":
+      typeDescription = (
+        <>
+          {schema.type} {schema.title ? `(${schema.title})` : ""}
+          {schema.nullable ? ` or null` : ""}
+        </>
+      )
+      break
+    case schema.type === "array":
+      typeDescription = (
+        <>
+          {schema.type === "array" && formatArrayDescription(schema.items)}
+          {schema.nullable ? ` or null` : ""}
+        </>
+      )
+      break
+    case schema.anyOf !== undefined:
+    case schema.allOf !== undefined:
+      typeDescription = (
+        <>
+          {formatUnionDescription(schema.allOf)}
+          {schema.nullable ? ` or null` : ""}
+        </>
+      )
+      break
+    case schema.oneOf !== undefined:
+      typeDescription = (
+        <>
+          {schema.oneOf?.map((item, index) => (
+            <Fragment key={index}>
+              {index !== 0 && <> or </>}
+              {item.type !== "array" && <>{item.title || item.type}</>}
+              {item.type === "array" && (
+                <>array{item.items.type ? ` of ${item.items.type}s` : ""}</>
+              )}
+            </Fragment>
+          ))}
+          {schema.nullable ? ` or null` : ""}
+        </>
+      )
+      break
+    default:
+      typeDescription = (
+        <>
+          {!schema.type ? "any" : schema.type}
+          {schema.nullable ? ` or null` : ""}
+          {schema.format ? ` <${schema.format}>` : ""}
+        </>
+      )
+  }
+
   return (
-    <span className="w-1/3 break-words pr-0.5">
+    <span className="inline-flex gap-0.5 items-center">
       <span className="font-monospace">{name}</span>
+      <span className="text-medusa-fg-muted text-compact-small">
+        {typeDescription}
+      </span>
       {schema.deprecated && (
         <Badge variant="orange" className="ml-1">
           deprecated
         </Badge>
       )}
       {schema["x-expandable"] && (
-        <>
-          <br />
-          <ExpandableNotice type="request" link="#expanding-relations" />
-        </>
+        <ExpandableNotice type="request" link="#expanding-relations" />
       )}
       {schema["x-featureFlag"] && (
-        <>
-          <br />
-          <FeatureFlagNotice
-            featureFlag={schema["x-featureFlag"]}
-            type="type"
-          />
-        </>
+        <FeatureFlagNotice featureFlag={schema["x-featureFlag"]} type="type" />
       )}
-      {isRequired && (
-        <>
-          <br />
-          <span className="text-medusa-tag-red-text text-compact-x-small">
-            required
-          </span>
-        </>
+      {!isRequired && (
+        <span className="text-medusa-tag-blue-text text-compact-x-small">
+          optional
+        </span>
       )}
     </span>
   )
 }
 
 export default TagOperationParametersName
+
+function formatArrayDescription(schema?: SchemaObject) {
+  if (!schema) {
+    return "Array"
+  }
+
+  const type =
+    schema.type === "object"
+      ? `objects ${schema.title ? `(${schema.title})` : ""}`
+      : `${schema.type || "object"}s`
+
+  return `Array of ${type}`
+}
+
+function formatUnionDescription(arr?: SchemaObject[]) {
+  const types = [...new Set(arr?.map((type) => type.type || "object"))]
+  return <>{types.join(" or ")}</>
+}

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

@@ -21,7 +21,7 @@ const TagOperationParametersDefault = ({
   return (
     <div
       className={clsx(
-        "my-0.5 inline-flex justify-between",
+        "my-0.5 inline-flex flex-col justify-between gap-0.25",
         expandable && "w-[calc(100%-16px)]",
         !expandable && "w-full pl-1",
         className

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

@@ -101,16 +101,20 @@ const TagOperationParametersObject = ({
     const content = (
       <>
         {sortedProperties.map((property, index) => (
-          <TagOperationParameters
-            schemaObject={{
-              ...properties[property],
-              parameterName: property,
-            }}
-            key={index}
-            isRequired={
-              properties[property].isRequired || checkRequired(schema, property)
-            }
-          />
+          <>
+            {index !== 0 && <hr className="bg-medusa-border-base my-0" />}
+            <TagOperationParameters
+              schemaObject={{
+                ...properties[property],
+                parameterName: property,
+              }}
+              key={index}
+              isRequired={
+                properties[property].isRequired ||
+                checkRequired(schema, property)
+              }
+            />
+          </>
         ))}
       </>
     )