docusaurus-theme-openapi-docs 4.7.0 → 5.0.0

package/lib/theme/Schema/index.js

@@ -84,8 +84,8 @@ const translationIds_1 = require("@theme/translationIds");
 // eslint-disable-next-line import/no-extraneous-dependencies
 const allof_merge_1 = require("allof-merge");
 const clsx_1 = __importDefault(require("clsx"));
-const schema_1 = require("docusaurus-plugin-openapi-docs/lib/markdown/schema");
 const isEmpty_1 = __importDefault(require("lodash/isEmpty"));
+const schema_1 = require("../../markdown/schema");
 // eslint-disable-next-line import/no-extraneous-dependencies
 // const jsonSchemaMergeAllOf = require("json-schema-merge-allof");
 const mergeAllOf = (allOf) => {
@@ -93,7 +93,68 @@ const mergeAllOf = (allOf) => {
     console.warn(msg);
   };
   const mergedSchemas = (0, allof_merge_1.merge)(allOf, { onMergeError });
-  return mergedSchemas;
+  return mergedSchemas ?? {};
+};
+/**
+ * Recursively searches for a property in a schema, including nested
+ * oneOf, anyOf, and allOf structures. This is needed for discriminators
+ * where the property definition may be in a nested schema.
+ */
+const findProperty = (schema, propertyName) => {
+  // Check direct properties first
+  if (schema.properties?.[propertyName]) {
+    return schema.properties[propertyName];
+  }
+  // Search in oneOf schemas
+  if (schema.oneOf) {
+    for (const subschema of schema.oneOf) {
+      const found = findProperty(subschema, propertyName);
+      if (found) return found;
+    }
+  }
+  // Search in anyOf schemas
+  if (schema.anyOf) {
+    for (const subschema of schema.anyOf) {
+      const found = findProperty(subschema, propertyName);
+      if (found) return found;
+    }
+  }
+  // Search in allOf schemas
+  if (schema.allOf) {
+    for (const subschema of schema.allOf) {
+      const found = findProperty(subschema, propertyName);
+      if (found) return found;
+    }
+  }
+  return undefined;
+};
+/**
+ * Recursively searches for a discriminator in a schema, including nested
+ * oneOf, anyOf, and allOf structures.
+ */
+const findDiscriminator = (schema) => {
+  if (schema.discriminator) {
+    return schema.discriminator;
+  }
+  if (schema.oneOf) {
+    for (const subschema of schema.oneOf) {
+      const found = findDiscriminator(subschema);
+      if (found) return found;
+    }
+  }
+  if (schema.anyOf) {
+    for (const subschema of schema.anyOf) {
+      const found = findDiscriminator(subschema);
+      if (found) return found;
+    }
+  }
+  if (schema.allOf) {
+    for (const subschema of schema.allOf) {
+      const found = findDiscriminator(subschema);
+      if (found) return found;
+    }
+  }
+  return undefined;
 };
 // Renders string as markdown, useful for descriptions and qualifiers
 const MarkdownWrapper = ({ text }) => {
@@ -165,6 +226,12 @@ const Summary = ({ name, schemaName, schema, required }) => {
 };
 const AnyOneOf = ({ schema, schemaType, schemaPath }) => {
   const key = schema.oneOf ? "oneOf" : "anyOf";
+  const schemaArray = schema[key];
+  // Empty oneOf/anyOf arrays are valid in OpenAPI specs but would cause the
+  // Tabs component to throw "requires at least one TabItem". Return null instead.
+  if (!schemaArray || !Array.isArray(schemaArray) || schemaArray.length === 0) {
+    return null;
+  }
   const type = schema.oneOf
     ? (0, Translate_1.translate)({
         id: translationIds_1.OPENAPI_SCHEMA_ITEM.ONE_OF,
@@ -244,9 +311,6 @@ const AnyOneOf = ({ schema, schemaType, schemaPath }) => {
                 collapsible: false,
                 name: undefined,
                 schemaName: computedSchemaName,
-                qualifierMessage: (0, schema_1.getQualifierMessage)(
-                  anyOneSchema
-                ),
                 schema: anyOneSchema,
                 discriminator: false,
                 children: null,
@@ -260,9 +324,6 @@ const AnyOneOf = ({ schema, schemaType, schemaPath }) => {
                 collapsible: false,
                 name: undefined,
                 schemaName: computedSchemaName,
-                qualifierMessage: (0, schema_1.getQualifierMessage)(
-                  anyOneSchema
-                ),
                 schema: anyOneSchema,
                 discriminator: false,
                 children: null,
@@ -321,12 +382,16 @@ const Properties = ({ schema, schemaType, schemaPath }) => {
     discriminator["mapping"] = inferredMapping;
   }
   if (Object.keys(schema.properties).length === 0) {
+    // Hide placeholder only for discriminator cleanup artifacts; preserve
+    // empty object rendering for schemas that intentionally define no properties.
+    if (discriminator) {
+      return null;
+    }
     return react_1.default.createElement(SchemaItem_1.default, {
       collapsible: false,
       name: "",
       required: false,
       schemaName: "object",
-      qualifierMessage: undefined,
       schema: {},
     });
   }
@@ -448,10 +513,9 @@ const PropertyDiscriminator = ({
 const DiscriminatorNode = ({ discriminator, schema, schemaType }) => {
   let discriminatedSchemas = {};
   let inferredMapping = {};
-  // default to empty object if no parent-level properties exist
-  const discriminatorProperty = schema.properties
-    ? schema.properties[discriminator.propertyName]
-    : {};
+  // Search for the discriminator property in the schema, including nested structures
+  const discriminatorProperty =
+    findProperty(schema, discriminator.propertyName) ?? {};
   if (schema.allOf) {
     const mergedSchemas = mergeAllOf(schema);
     if (mergedSchemas.oneOf || mergedSchemas.anyOf) {
@@ -523,7 +587,6 @@ const AdditionalProperties = ({ schema, schemaType }) => {
       name: "property name*",
       required: false,
       schemaName: "any",
-      qualifierMessage: (0, schema_1.getQualifierMessage)(schema),
       schema: schema,
       collapsible: false,
       discriminator: false,
@@ -564,7 +627,6 @@ const AdditionalProperties = ({ schema, schemaType }) => {
       name: "property name*",
       required: false,
       schemaName: schemaName,
-      qualifierMessage: (0, schema_1.getQualifierMessage)(schema),
       schema: additionalProperties,
       collapsible: false,
       discriminator: false,
@@ -669,7 +731,6 @@ const Items = ({ schema, schemaType, schemaPath }) => {
         collapsible: false,
         name: "", // No name for array items
         schemaName: (0, schema_1.getSchemaName)(itemsSchema),
-        qualifierMessage: (0, schema_1.getQualifierMessage)(itemsSchema),
         schema: itemsSchema,
         discriminator: false,
         children: null,
@@ -790,7 +851,6 @@ const SchemaEdge = ({
         name: name,
         required: Array.isArray(required) ? required.includes(name) : required,
         schemaName: schema.allOf[0],
-        qualifierMessage: undefined,
         schema: schema.allOf[0],
         discriminator: false,
         children: null,
@@ -842,7 +902,6 @@ const SchemaEdge = ({
       name: name,
       required: Array.isArray(required) ? required.includes(name) : required,
       schemaName: mergedSchemaName,
-      qualifierMessage: (0, schema_1.getQualifierMessage)(mergedSchemas),
       schema: mergedSchemas,
       discriminator: false,
       children: null,
@@ -853,7 +912,6 @@ const SchemaEdge = ({
     name: name,
     required: Array.isArray(required) ? required.includes(name) : required,
     schemaName: schemaName,
-    qualifierMessage: (0, schema_1.getQualifierMessage)(schema),
     schema: schema,
     discriminator: false,
     children: null,
@@ -901,11 +959,22 @@ const SchemaNode = ({ schema, schemaType, schemaPath }) => {
   ) {
     return null;
   }
-  if (schema.discriminator) {
-    const { discriminator } = schema;
+  // Resolve discriminator recursively so nested oneOf/anyOf/allOf compositions
+  // can still render discriminator tabs.
+  let workingSchema = schema;
+  const resolvedDiscriminator =
+    schema.discriminator ?? findDiscriminator(schema);
+  if (schema.allOf && !schema.discriminator && resolvedDiscriminator) {
+    workingSchema = mergeAllOf(schema);
+  }
+  if (!workingSchema.discriminator && resolvedDiscriminator) {
+    workingSchema.discriminator = resolvedDiscriminator;
+  }
+  if (workingSchema.discriminator) {
+    const { discriminator } = workingSchema;
     return react_1.default.createElement(DiscriminatorNode, {
       discriminator: discriminator,
-      schema: schema,
+      schema: workingSchema,
       schemaType: schemaType,
     });
   }
@@ -1010,7 +1079,6 @@ const SchemaNode = ({ schema, schemaType, schemaPath }) => {
       name: schema.type,
       required: Boolean(schema.required),
       schemaName: schemaName,
-      qualifierMessage: (0, schema_1.getQualifierMessage)(schema),
       schema: schema,
       discriminator: false,
       children: null,

package/lib/theme/SchemaItem/index.js

@@ -18,6 +18,7 @@ const Example_1 = require("@theme/Example");
 const Markdown_1 = __importDefault(require("@theme/Markdown"));
 const translationIds_1 = require("@theme/translationIds");
 const clsx_1 = __importDefault(require("clsx"));
+const schema_1 = require("../../markdown/schema");
 const utils_1 = require("../../markdown/utils");
 const transformEnumDescriptions = (enumDescriptions) => {
   if (enumDescriptions) {
@@ -127,8 +128,12 @@ function SchemaItem(props) {
         react_1.default.createElement(Markdown_1.default, null, description)
       )
   );
+  // Generate qualifierMessage from schema if not provided
+  const effectiveQualifierMessage =
+    qualifierMessage ??
+    (schema ? (0, schema_1.getQualifierMessage)(schema) : undefined);
   const renderQualifierMessage = (0, utils_1.guard)(
-    qualifierMessage,
+    effectiveQualifierMessage,
     (message) =>
       react_1.default.createElement(
         react_1.default.Fragment,

package/lib/theme/SchemaTabs/index.d.ts

@@ -7,4 +7,4 @@ export interface SchemaTabsProps extends TabProps {
      */
     onChange?: (index: number) => void;
 }
-export default function SchemaTabs(props: SchemaTabsProps): React.JSX.Element;
+export default function SchemaTabs(props: SchemaTabsProps): React.JSX.Element | null;

package/lib/theme/SchemaTabs/index.js

@@ -233,25 +233,44 @@ function TabContent({ lazy, children, selectedValue }) {
   return react_1.default.createElement(
     "div",
     { className: "margin-top--md" },
-    childTabs.map((tabItem, i) =>
-      (0, react_1.cloneElement)(tabItem, {
-        key: i,
-        hidden: tabItem.props.value !== selectedValue,
-      })
-    )
+    childTabs
   );
 }
 function TabsComponent(props) {
-  const tabs = (0, internal_1.useTabs)(props);
+  const tabs = (0, internal_1.useTabsContextValue)(props);
   return react_1.default.createElement(
-    "div",
-    { className: "openapi-tabs__schema-container" },
-    react_1.default.createElement(TabList, { ...props, ...tabs }),
-    react_1.default.createElement(TabContent, { ...props, ...tabs })
+    internal_1.TabsProvider,
+    { value: tabs },
+    react_1.default.createElement(
+      "div",
+      { className: "openapi-tabs__schema-container" },
+      react_1.default.createElement(TabList, { ...props, ...tabs }),
+      react_1.default.createElement(TabContent, { ...props, ...tabs })
+    )
   );
 }
 function SchemaTabs(props) {
   const isBrowser = (0, useIsBrowser_1.default)();
+  const children = Array.isArray(props.children)
+    ? props.children.filter(Boolean)
+    : props.children
+      ? [props.children]
+      : [];
+  if (children.length === 0) {
+    return null;
+  }
+  let sanitizedChildren;
+  try {
+    sanitizedChildren = (0, internal_1.sanitizeTabsChildren)(children);
+  } catch {
+    return null;
+  }
+  if (
+    !sanitizedChildren ||
+    (Array.isArray(sanitizedChildren) && sanitizedChildren.length === 0)
+  ) {
+    return null;
+  }
   return react_1.default.createElement(
     TabsComponent,
     // Remount tabs after hydration
@@ -262,6 +281,6 @@ function SchemaTabs(props) {
       key: String(isBrowser),
       ...props,
     },
-    (0, internal_1.sanitizeTabsChildren)(props.children)
+    sanitizedChildren
   );
 }

package/lib/theme/StatusCodes/index.d.ts

@@ -1,5 +1,5 @@
 import React from "react";
-import { ApiItem } from "docusaurus-plugin-openapi-docs/src/types";
+import type { ApiItem } from "docusaurus-plugin-openapi-docs/src/types";
 interface Props {
     id?: string;
     label?: string;

package/lib/theme/styles.scss

@@ -9,6 +9,7 @@
 @use "./ApiExplorer/FloatingButton/FloatingButton";
 @use "./ApiExplorer/FormFileUpload/FormFileUpload";
 @use "./ApiExplorer/FormItem/FormItem";
+@use "./ApiExplorer/FormLabel/FormLabel";
 @use "./ApiExplorer/FormMultiSelect/FormMultiSelect";
 @use "./ApiExplorer/FormSelect/FormSelect";
 @use "./ApiExplorer/FormTextInput/FormTextInput";

package/lib/theme/translationIds.d.ts

@@ -60,6 +60,8 @@ export declare const OPENAPI_SCHEMA: {
     NO_SCHEMA: string;
 };
 export declare const OPENAPI_SCHEMA_ITEM: {
+    CHARACTERS: string;
+    NON_EMPTY: string;
     REQUIRED: string;
     DEPRECATED: string;
     NULLABLE: string;
@@ -71,6 +73,7 @@ export declare const OPENAPI_SCHEMA_ITEM: {
     ENUM_VALUE: string;
     ENUM_DESCRIPTION: string;
     POSSIBLE_VALUES: string;
+    EXPRESSION: string;
     ONE_OF: string;
     ANY_OF: string;
 };

package/lib/theme/translationIds.js

@@ -84,6 +84,8 @@ exports.OPENAPI_SCHEMA = {
   NO_SCHEMA: "theme.openapi.schema.noSchema",
 };
 exports.OPENAPI_SCHEMA_ITEM = {
+  CHARACTERS: "theme.openapi.schemaItem.characters",
+  NON_EMPTY: "theme.openapi.schemaItem.nonEmpty",
   REQUIRED: "theme.openapi.schemaItem.required",
   DEPRECATED: "theme.openapi.schemaItem.deprecated",
   NULLABLE: "theme.openapi.schemaItem.nullable",
@@ -95,6 +97,7 @@ exports.OPENAPI_SCHEMA_ITEM = {
   ENUM_VALUE: "theme.openapi.schemaItem.enumValue",
   ENUM_DESCRIPTION: "theme.openapi.schemaItem.enumDescription",
   POSSIBLE_VALUES: "theme.openapi.schemaItem.possibleValues",
+  EXPRESSION: "theme.openapi.schemaItem.expression",
   ONE_OF: "theme.openapi.schemaItem.oneOf",
   ANY_OF: "theme.openapi.schemaItem.anyOf",
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-theme-openapi-docs",
   "description": "OpenAPI theme for Docusaurus.",
-  "version": "4.7.0",
+  "version": "5.0.0",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -28,9 +28,9 @@
     "watch": "concurrently --names \"lib,lib-next,tsc\" --kill-others \"yarn babel:lib --watch\" \"yarn babel:lib-next --watch\" \"yarn tsc --watch\""
   },
   "devDependencies": {
-    "@docusaurus/theme-classic": "^3.5.0",
-    "@docusaurus/theme-common": "^3.5.0",
-    "@docusaurus/types": "^3.5.0",
+    "@docusaurus/theme-classic": "^3.10.0",
+    "@docusaurus/theme-common": "^3.10.0",
+    "@docusaurus/types": "^3.10.0",
     "@types/crypto-js": "^4.2.2",
     "@types/file-saver": "^2.0.7",
     "@types/lodash": "^4.17.20",
@@ -38,7 +38,7 @@
     "@types/postman-collection": "^3.5.11",
     "@types/react-modal": "^3.16.3",
     "concurrently": "^9.2.0",
-    "docusaurus-plugin-openapi-docs": "^4.7.0",
+    "docusaurus-plugin-openapi-docs": "^5.0.0",
     "docusaurus-plugin-sass": "^0.2.6",
     "eslint-plugin-prettier": "^5.5.1"
   },
@@ -53,6 +53,7 @@
     "file-saver": "^2.0.5",
     "lodash": "^4.17.21",
     "pako": "^2.1.0",
+    "path-browserify": "^1.0.1",
     "postman-code-generators": "^2.0.0",
     "postman-collection": "^5.0.2",
     "prism-react-renderer": "^2.4.1",
@@ -72,8 +73,8 @@
     "xml-formatter": "^3.6.6"
   },
   "peerDependencies": {
-    "@docusaurus/theme-common": "^3.5.0",
-    "docusaurus-plugin-openapi-docs": "^4.0.0",
+    "@docusaurus/theme-common": "^3.10.0",
+    "docusaurus-plugin-openapi-docs": "^5.0.0",
     "docusaurus-plugin-sass": "^0.2.3",
     "react": "^16.8.4 || ^17.0.0 || ^18.0.0 || ^19.0.0",
     "react-dom": "^16.8.4 || ^17.0.0 || ^18.0.0 || ^19.0.0"
@@ -81,5 +82,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "f5829b8e478b0ee76344ba31edd67efdfea18990"
+  "gitHead": "516bd48c628fb16b7fe90d8f996168ab75ce5562"
 }

package/src/index.ts

@@ -42,6 +42,7 @@ export default function docusaurusThemeOpenAPI(): Plugin<void> {
           resolve: {
             fallback: {
               buffer: require.resolve("buffer/"),
+              path: require.resolve("path-browserify"),
             },
           },
           plugins: [
@@ -71,6 +72,7 @@ export default function docusaurusThemeOpenAPI(): Plugin<void> {
         resolve: {
           fallback: {
             buffer: require.resolve("buffer/"),
+            path: require.resolve("path-browserify"),
           },
         },
         plugins: [

package/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,11 +136,11 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
 
   let qualifierGroups = [];
 
-  if (schema.items && schema.items.enum) {
-    if (schema.items.enum) {
-      qualifierGroups.push(
-        `[${schema.items.enum.map((e) => `\`${e}\``).join(", ")}]`
-      );
+  // Check for enum in array items (directly or inside allOf)
+  if (schema.items) {
+    const itemsEnum = getEnumFromSchema(schema.items as SchemaObject);
+    if (itemsEnum) {
+      qualifierGroups.push(`[${itemsEnum.map((e) => `\`${e}\``).join(", ")}]`);
     }
   }
 
@@ -104,14 +148,22 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
     let lengthQualifier = "";
     let minLength;
     let maxLength;
+    const charactersMessage = translate({
+      id: OPENAPI_SCHEMA_ITEM.CHARACTERS,
+      message: "characters",
+    });
+    const nonEmptyMessage = translate({
+      id: OPENAPI_SCHEMA_ITEM.NON_EMPTY,
+      message: "non-empty",
+    });
     if (schema.minLength && schema.minLength > 1) {
-      minLength = `\`>= ${schema.minLength} characters\``;
+      minLength = `\`>= ${schema.minLength} ${charactersMessage}\``;
     }
     if (schema.minLength && schema.minLength === 1) {
-      minLength = `\`non-empty\``;
+      minLength = `\`${nonEmptyMessage}\``;
     }
     if (schema.maxLength) {
-      maxLength = `\`<= ${schema.maxLength} characters\``;
+      maxLength = `\`<= ${schema.maxLength} ${charactersMessage}\``;
     }
 
     if (minLength && !maxLength) {
@@ -165,9 +217,11 @@ export function getQualifierMessage(schema?: SchemaObject): string | undefined {
   }
 
   if (schema.pattern) {
-    qualifierGroups.push(
-      `Value must match regular expression \`${schema.pattern}\``
-    );
+    const expressionMessage = translate({
+      id: OPENAPI_SCHEMA_ITEM.EXPRESSION,
+      message: "Value must match regular expression",
+    });
+    qualifierGroups.push(`${expressionMessage} \`${schema.pattern}\``);
   }
 
   // Check if discriminator mapping
@@ -177,8 +231,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) {

package/src/theme/ApiExplorer/Accept/index.tsx

@@ -23,8 +23,9 @@ function Accept() {
   }
 
   return (
-    <FormItem label="Accept">
+    <FormItem>
       <FormSelect
+        label="Accept"
         value={value}
         options={options}
         onChange={(e: any) => dispatch(setAccept(e.target.value))}