fix(theme): show dropdown for enum parameters wrapped in allOf (#1301)

Add support for detecting enum values inside allOf schemas when
rendering parameter form inputs and schema documentation. Previously,
enums wrapped in allOf (e.g., for nullable enum refs) would incorrectly
render as text inputs and show "object" type instead of displaying the
actual enum values.

Changes:
- Add getSchemaEnum() helper to ParamOptions for form input detection
- Add getEnumFromSchema() and getTypeFromSchema() helpers to schema.ts
- Update prettyName() to return correct type for allOf with enums
- Update getQualifierMessage() to show enum values from allOf
- Update ParamSelectFormItem to extract enum from allOf
- Update ParamMultiSelectFormItem to extract enum from allOf for arrays
- Add test case in demo/examples/tests/allOf.yaml
- Add servers to allOf.yaml spec for API Explorer testing
- Enable API Explorer for test specs (hideSendButton: false)

Fixes #1233

Author: sserrata

demo/docusaurus.config.ts

@@ -366,7 +366,7 @@ const config: Config = {
               groupPathsBy: "tag",
               categoryLinkSource: "info",
             },
-            hideSendButton: true,
+            hideSendButton: false,
             showSchemas: true,
           } satisfies OpenApiPlugin.Options,
         } satisfies Plugin.PluginOptions,

demo/examples/tests/allOf.yaml

@@ -3,6 +3,9 @@ info:
   title: AllOf Variations API
   description: Demonstrates various allOf schema combinations.
   version: 1.0.0
+servers:
+  - url: https://api.example.com/v1
+    description: Example API server
 tags:
   - name: allOf
     description: allOf tests
@@ -412,6 +415,66 @@ paths:
                 required:
                   - pet
 
+  /allof-enum-parameter:
+    get:
+      tags:
+        - allOf
+      summary: allOf with Enum Parameter
+      description: |
+        Demonstrates that enum parameters wrapped in allOf should render as a dropdown/combobox
+        instead of a text input.
+
+        Parameter Schema:
+        ```yaml
+        name: status
+        in: query
+        schema:
+          nullable: true
+          allOf:
+            - $ref: '#/components/schemas/TaskStatus'
+        ```
+
+        Where TaskStatus is:
+        ```yaml
+        TaskStatus:
+          type: string
+          enum: [Pending, InProgress, Completed, Cancelled]
+        ```
+      parameters:
+        - name: status
+          in: query
+          description: Filter by task status (should show as dropdown)
+          schema:
+            nullable: true
+            allOf:
+              - $ref: "#/components/schemas/TaskStatus"
+        - name: priorities
+          in: query
+          description: Filter by multiple priorities (should show as multi-select)
+          schema:
+            type: array
+            items:
+              allOf:
+                - $ref: "#/components/schemas/Priority"
+      responses:
+        "200":
+          description: A list of tasks
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    id:
+                      type: integer
+                    name:
+                      type: string
+                    status:
+                      $ref: "#/components/schemas/TaskStatus"
+                    priority:
+                      $ref: "#/components/schemas/Priority"
+
   /allof-multiple-oneof:
     post:
       tags:
@@ -613,14 +676,24 @@ paths:
 
 components:
   schemas:
-    # Your existing schemas are integrated here.
-    ExistingSchema1:
-      type: object
-      properties: ...
+    # Enum schemas for allOf parameter tests
+    TaskStatus:
+      type: string
+      description: The status of a task
+      enum:
+        - Pending
+        - InProgress
+        - Completed
+        - Cancelled
 
-    ExistingSchema2:
-      type: object
-      properties: ...
+    Priority:
+      type: string
+      description: Priority level
+      enum:
+        - Low
+        - Medium
+        - High
+        - Critical
 
     # New schemas for Books demonstration
     BookBase:

packages/docusaurus-theme-openapi-docs/src/markdown/schema.ts

@@ -10,6 +10,44 @@ import { translate } from "@docusaurus/Translate";
 import { OPENAPI_SCHEMA_ITEM } from "../theme/translationIds";
 import { SchemaObject } from "../types";
 
+/**
+ * Extracts enum values from a schema, including when wrapped in allOf.
+ */
+function getEnumFromSchema(schema: SchemaObject): any[] | undefined {
+  if (schema.enum) {
+    return schema.enum;
+  }
+
+  if (schema.allOf && Array.isArray(schema.allOf)) {
+    for (const item of schema.allOf) {
+      if (item.enum) {
+        return item.enum;
+      }
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Extracts the type from a schema, including when wrapped in allOf.
+ */
+function getTypeFromSchema(schema: SchemaObject): string | undefined {
+  if (schema.type) {
+    return schema.type as string;
+  }
+
+  if (schema.allOf && Array.isArray(schema.allOf)) {
+    for (const item of schema.allOf) {
+      if (item.type) {
+        return item.type as string;
+      }
+    }
+  }
+
+  return undefined;
+}
+
 function prettyName(schema: SchemaObject, circular?: boolean) {
   // Handle enum-only schemas (valid in JSON Schema)
   // When enum is present without explicit type, treat as string
@@ -28,6 +66,12 @@ function prettyName(schema: SchemaObject, circular?: boolean) {
         return schema.allOf[0];
       }
     }
+    // Check if allOf contains an enum - if so, return the type from allOf
+    const enumFromAllOf = getEnumFromSchema(schema);
+    if (enumFromAllOf) {
+      const typeFromAllOf = getTypeFromSchema(schema);
+      return typeFromAllOf ?? "string";
+    }
     return "object";
   }
 
@@ -92,10 +136,12 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
 
   let qualifierGroups = [];
 
-  if (schema.items && schema.items.enum) {
-    if (schema.items.enum) {
+  // Check for enum in array items (directly or inside allOf)
+  if (schema.items) {
+    const itemsEnum = getEnumFromSchema(schema.items as SchemaObject);
+    if (itemsEnum) {
       qualifierGroups.push(
-        `[${schema.items.enum.map((e) => `\`${e}\``).join(", ")}]`
+        `[${itemsEnum.map((e) => `\`${e}\``).join(", ")}]`
       );
     }
   }
@@ -177,8 +223,10 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
     qualifierGroups.push(`[${values.map((e) => `\`${e}\``).join(", ")}]`);
   }
 
-  if (schema.enum) {
-    qualifierGroups.push(`[${schema.enum.map((e) => `\`${e}\``).join(", ")}]`);
+  // Check for enum directly on schema or inside allOf
+  const schemaEnum = getEnumFromSchema(schema);
+  if (schemaEnum) {
+    qualifierGroups.push(`[${schemaEnum.map((e) => `\`${e}\``).join(", ")}]`);
   }
 
   if (schema.minItems) {

packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/ParamOptions/ParamFormItems/ParamMultiSelectFormItem.tsx

@@ -10,6 +10,7 @@ import React from "react";
 import { translate } from "@docusaurus/Translate";
 import { ErrorMessage } from "@hookform/error-message";
 import FormMultiSelect from "@theme/ApiExplorer/FormMultiSelect";
+import { getSchemaEnum } from "@theme/ApiExplorer/ParamOptions";
 import { Param, setParam } from "@theme/ApiExplorer/ParamOptions/slice";
 import { useTypedDispatch, useTypedSelector } from "@theme/ApiItem/hooks";
 import { OPENAPI_FORM } from "@theme/translationIds";
@@ -29,7 +30,7 @@ export default function ParamMultiSelectFormItem({ param }: ParamProps) {
 
   const dispatch = useTypedDispatch();
 
-  const options = param.schema?.items?.enum ?? [];
+  const options = getSchemaEnum(param.schema?.items) ?? [];
 
   const pathParams = useTypedSelector((state: any) => state.params.path);
   const queryParams = useTypedSelector((state: any) => state.params.query);

packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/ParamOptions/ParamFormItems/ParamSelectFormItem.tsx

@@ -10,6 +10,7 @@ import React from "react";
 import { translate } from "@docusaurus/Translate";
 import { ErrorMessage } from "@hookform/error-message";
 import FormSelect from "@theme/ApiExplorer/FormSelect";
+import { getSchemaEnum } from "@theme/ApiExplorer/ParamOptions";
 import { Param, setParam } from "@theme/ApiExplorer/ParamOptions/slice";
 import { useTypedDispatch } from "@theme/ApiItem/hooks";
 import { OPENAPI_FORM } from "@theme/translationIds";
@@ -29,7 +30,7 @@ export default function ParamSelectFormItem({ param }: ParamProps) {
 
   const dispatch = useTypedDispatch();
 
-  const options = param.schema?.enum ?? [];
+  const options = getSchemaEnum(param.schema) ?? [];
 
   return (
     <>

packages/docusaurus-theme-openapi-docs/src/theme/ApiExplorer/ParamOptions/index.tsx

@@ -23,16 +23,41 @@ export interface ParamProps {
   param: Param;
 }
 
+/**
+ * Extracts enum values from a schema, including when wrapped in allOf.
+ * This handles cases where an enum is referenced via allOf for composition.
+ */
+export function getSchemaEnum(schema: any): any[] | undefined {
+  // Direct enum on schema
+  if (schema?.enum) {
+    return schema.enum;
+  }
+
+  // Enum inside allOf - check each item
+  if (schema?.allOf && Array.isArray(schema.allOf)) {
+    for (const item of schema.allOf) {
+      if (item.enum) {
+        return item.enum;
+      }
+    }
+  }
+
+  return undefined;
+}
+
 function ParamOption({ param }: ParamProps) {
-  if (param.schema?.type === "array" && param.schema.items?.enum) {
+  const schemaEnum = getSchemaEnum(param.schema);
+  const itemsEnum = getSchemaEnum(param.schema?.items);
+
+  if (param.schema?.type === "array" && itemsEnum) {
     return <ParamMultiSelectFormItem param={param} />;
   }
 
   if (param.schema?.type === "array") {
     return <ParamArrayFormItem param={param} />;
   }
 
-  if (param.schema?.enum) {
+  if (schemaEnum) {
     return <ParamSelectFormItem param={param} />;
   }