Use x-enumDescriptions in UI

Author: omonk

demo/examples/petstore.yaml

@@ -351,6 +351,10 @@ paths:
                 - available
                 - pending
                 - sold
+              x-enumDescriptions:
+                available: When the pet is available
+                pending: When the pet is being sold
+                sold: When the pet has been sold
               default: available
       responses:
         "200":
@@ -1114,6 +1118,15 @@ components:
             - available
             - pending
             - sold
+          x-enumDescriptions:
+            available: When the pet is available
+            pending: When the pet is being sold
+            sold: |
+              When the pet has been sold.
+
+              These descriptions can contain line
+
+              breaks and also [links](https://docusaurus.io/)
         petType:
           description: Type of a pet
           type: string

packages/docusaurus-plugin-openapi-docs/src/markdown/createParamsDetails.ts

@@ -43,12 +43,17 @@ export function createParamsDetails({ parameters, type }: Props) {
       create("div", {
         children: [
           create("ul", {
-            children: params.map((param) =>
-              create("ParamsItem", {
+            children: params.map((param) => {
+              return create("ParamsItem", {
                 className: "paramsItem",
-                param: param,
-              })
-            ),
+                param: {
+                  ...param,
+                  enumDescriptions: Object.entries(
+                    param?.schema?.items?.["x-enumDescriptions"] ?? {}
+                  ),
+                },
+              });
+            }),
           }),
         ],
       }),

packages/docusaurus-plugin-openapi-docs/src/openapi/types.ts

@@ -197,6 +197,7 @@ export interface ParameterObject {
   param?: Object;
   // ignoring stylings: matrix, label, form, simple, spaceDelimited,
   // pipeDelimited and deepObject
+  "x-enumDescriptions": Record<string, string>;
 }
 
 export interface ParameterObjectWithRef {
@@ -353,6 +354,7 @@ export type SchemaObject = Omit<
   example?: any;
   deprecated?: boolean;
   "x-tags"?: string[];
+  "x-enumDescriptions"?: Record<string, string>;
 };
 
 export type SchemaObjectWithRef = Omit<

packages/docusaurus-plugin-openapi-docs/src/openapi/utils/services/OpenAPIParser.ts

@@ -270,6 +270,7 @@ export class OpenAPIParser {
       const {
         type,
         enum: enumProperty,
+        "x-enumDescription": enumDescription,
         properties,
         items,
         required,

packages/docusaurus-theme-openapi-docs/package.json

@@ -57,6 +57,7 @@
     "react-modal": "^3.15.1",
     "react-redux": "^7.2.0",
     "rehype-raw": "^6.1.1",
+    "remark-gfm": "3.0.1",
     "sass": "^1.58.1",
     "sass-loader": "^13.3.2",
     "webpack": "^5.61.0",

packages/docusaurus-theme-openapi-docs/src/theme/ParamsItem/index.tsx

@@ -14,6 +14,7 @@ import TabItem from "@theme/TabItem";
 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 { getQualifierMessage, getSchemaName } from "../../markdown/schema";
@@ -39,12 +40,38 @@ export interface Props {
     required: boolean;
     deprecated: boolean;
     schema: any;
+    enumDescriptions?: [string, string][];
   };
 }
 
-function ParamsItem({
-  param: { description, example, examples, name, required, schema, deprecated },
-}: Props) {
+const getEnumDescriptionMarkdown = (enumDescriptions?: [string, string][]) => {
+  if (enumDescriptions?.length) {
+    return `| Enum | Description |
+| ---- | ----- |
+${enumDescriptions
+  .map((desc) => {
+    return `| ${desc[0]} | ${desc[1]} | `.replaceAll("\n", "<br/>");
+  })
+  .join("\n")}
+    `;
+  }
+
+  return "";
+};
+
+function ParamsItem({ param, ...rest }: Props) {
+  const {
+    description,
+    example,
+    examples,
+    name,
+    required,
+    deprecated,
+    enumDescriptions,
+  } = param;
+
+  let schema = param.schema;
+
   if (!schema || !schema?.type) {
     schema = { type: "any" };
   }
@@ -91,6 +118,19 @@ function ParamsItem({
     </div>
   ));
 
+  const renderEnumDescriptions = guard(
+    getEnumDescriptionMarkdown(enumDescriptions),
+    (value) => {
+      return (
+        <ReactMarkdown
+          rehypePlugins={[rehypeRaw]}
+          remarkPlugins={[remarkGfm]}
+          children={value}
+        />
+      );
+    }
+  );
+
   const renderDefaultValue = guard(
     schema && schema.items
       ? schema.items.default
@@ -158,6 +198,7 @@ function ParamsItem({
       {renderSchema}
       {renderDefaultValue}
       {renderDescription}
+      {renderEnumDescriptions}
       {renderExample}
       {renderExamples}
     </div>

packages/docusaurus-theme-openapi-docs/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,22 +28,52 @@ 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 | 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;
+  console.log({ props });
   let deprecated;
   let schemaDescription;
   let defaultValue;
   let nullable;
+  let enumDescriptions: [string, string][] = [];
+
   if (schema) {
     deprecated = schema.deprecated;
     schemaDescription = schema.description;
+    enumDescriptions = transformEnumDescriptions(schema["x-enumDescriptions"]);
     defaultValue = schema.default;
     nullable = schema.nullable;
   }
@@ -60,6 +91,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
@@ -117,6 +161,7 @@ export default function SchemaItem({
       {renderQualifierMessage}
       {renderDefaultValue}
       {renderSchemaDescription}
+      {renderEnumDescriptions}
       {collapsibleSchemaContent ?? collapsibleSchemaContent}
     </div>
   );