docusaurus-theme-openapi-docs 4.0.0 → 4.1.0

package/src/theme/SchemaItem/index.tsx

@@ -11,6 +11,7 @@ import CodeBlock from "@theme/CodeBlock";
 import clsx from "clsx";
 import ReactMarkdown from "react-markdown";
 import rehypeRaw from "rehype-raw";
+import remarkGfm from "remark-gfm";
 
 import { createDescription } from "../../markdown/createDescription";
 import { guard } from "../../markdown/utils";
@@ -27,23 +28,54 @@ export interface Props {
   discriminator: boolean;
 }
 
-export default function SchemaItem({
-  children: collapsibleSchemaContent,
-  collapsible,
-  name,
-  qualifierMessage,
-  required,
-  schemaName,
-  schema,
-}: Props) {
+const transformEnumDescriptions = (
+  enumDescriptions?: Record<string, string>
+) => {
+  if (enumDescriptions) {
+    return Object.entries(enumDescriptions);
+  }
+
+  return [];
+};
+
+const getEnumDescriptionMarkdown = (enumDescriptions?: [string, string][]) => {
+  if (enumDescriptions?.length) {
+    return `| Enum Value | Description |
+| ---- | ----- |
+${enumDescriptions
+  .map((desc) => {
+    return `| ${desc[0]} | ${desc[1]} | `.replaceAll("\n", "<br/>");
+  })
+  .join("\n")}
+    `;
+  }
+
+  return "";
+};
+
+export default function SchemaItem(props: Props) {
+  const {
+    children: collapsibleSchemaContent,
+    collapsible,
+    name,
+    qualifierMessage,
+    required,
+    schemaName,
+    schema,
+  } = props;
   let deprecated;
   let schemaDescription;
-  let defaultValue;
+  let defaultValue: string | undefined;
+  let example: string | undefined;
   let nullable;
+  let enumDescriptions: [string, string][] = [];
+
   if (schema) {
     deprecated = schema.deprecated;
     schemaDescription = schema.description;
+    enumDescriptions = transformEnumDescriptions(schema["x-enumDescriptions"]);
     defaultValue = schema.default;
+    example = schema.example;
     nullable = schema.nullable;
   }
 
@@ -60,6 +92,19 @@ export default function SchemaItem({
     <span className="openapi-schema__nullable">nullable</span>
   ));
 
+  const renderEnumDescriptions = guard(
+    getEnumDescriptionMarkdown(enumDescriptions),
+    (value) => {
+      return (
+        <ReactMarkdown
+          remarkPlugins={[remarkGfm]}
+          rehypePlugins={[rehypeRaw]}
+          children={value}
+        />
+      );
+    }
+  );
+
   const renderSchemaDescription = guard(schemaDescription, (description) => (
     <div>
       <ReactMarkdown
@@ -90,11 +135,53 @@ export default function SchemaItem({
     </div>
   ));
 
-  const renderDefaultValue = guard(defaultValue, (value) => (
-    <div className="">
-      <ReactMarkdown children={`**Default value:** \`${value}\``} />
-    </div>
-  ));
+  function renderDefaultValue() {
+    if (defaultValue !== undefined) {
+      if (typeof defaultValue === "string") {
+        return (
+          <div>
+            <strong>Default value: </strong>
+            <span>
+              <code>{defaultValue}</code>
+            </span>
+          </div>
+        );
+      }
+      return (
+        <div>
+          <strong>Default value: </strong>
+          <span>
+            <code>{JSON.stringify(defaultValue)}</code>
+          </span>
+        </div>
+      );
+    }
+    return undefined;
+  }
+
+  function renderExample() {
+    if (example !== undefined) {
+      if (typeof example === "string") {
+        return (
+          <div>
+            <strong>Example: </strong>
+            <span>
+              <code>{example}</code>
+            </span>
+          </div>
+        );
+      }
+      return (
+        <div>
+          <strong>Example: </strong>
+          <span>
+            <code>{JSON.stringify(example)}</code>
+          </span>
+        </div>
+      );
+    }
+    return undefined;
+  }
 
   const schemaContent = (
     <div>
@@ -114,9 +201,11 @@ export default function SchemaItem({
         {renderRequired}
         {renderDeprecated}
       </span>
-      {renderQualifierMessage}
-      {renderDefaultValue}
       {renderSchemaDescription}
+      {renderEnumDescriptions}
+      {renderQualifierMessage}
+      {renderDefaultValue()}
+      {renderExample()}
       {collapsibleSchemaContent ?? collapsibleSchemaContent}
     </div>
   );

package/src/theme-classic.d.ts

@@ -27,8 +27,6 @@ declare module "@docusaurus/theme-common/internal" {
   export interface LineProps extends ILineProps {}
   export interface CodeBlockProps extends ICodeBlockProps {}
 
-  export function useDoc();
-
   export function usePrismTheme(): PrismTheme;
 
   export function sanitizeTabsChildren(children: TabProps["children"]);

package/src/theme-openapi.d.ts

@@ -54,6 +54,10 @@ declare module "@theme/ApiItem/hooks" {
 }
 
 declare module "@theme/ApiItem/Layout" {
+  export interface Props {
+    readonly children: JSX.Element;
+  }
+
   export default function Layout(props: any): JSX.Element;
 }