docusaurus-theme-openapi-docs 5.0.1 → 5.1.0

package/src/theme/ParamsDetails/index.tsx

@@ -12,7 +12,6 @@ import { translate } from "@docusaurus/Translate";
 import Details from "@theme/Details";
 import ParamsItem from "@theme/ParamsItem";
 import SkeletonLoader from "@theme/SkeletonLoader";
-import { OPENAPI_PARAMS_DETAILS } from "@theme/translationIds";
 
 interface Props {
   parameters: any[];
@@ -35,7 +34,7 @@ const ParamsDetailsComponent: React.FC<Props> = ({ parameters }) => {
             <h3 className="openapi-markdown__details-summary-header-params">
               {translate(
                 {
-                  id: OPENAPI_PARAMS_DETAILS.PARAMETERS_TITLE,
+                  id: "theme.openapi.paramsDetails.parametersTitle",
                   message: "{type} Parameters",
                 },
                 { type: type.charAt(0).toUpperCase() + type.slice(1) }

package/src/theme/ParamsItem/index.tsx

@@ -11,7 +11,6 @@ import { translate } from "@docusaurus/Translate";
 import { Example } from "@theme/Example";
 import Markdown from "@theme/Markdown";
 /* eslint-disable import/no-extraneous-dependencies*/
-import { OPENAPI_SCHEMA_ITEM } from "@theme/translationIds";
 import clsx from "clsx";
 
 import { getQualifierMessage, getSchemaName } from "../../markdown/schema";
@@ -41,11 +40,11 @@ export interface Props {
 const getEnumDescriptionMarkdown = (enumDescriptions?: [string, string][]) => {
   if (enumDescriptions?.length) {
     const enumValue = translate({
-      id: OPENAPI_SCHEMA_ITEM.ENUM_VALUE,
+      id: "theme.openapi.schemaItem.enumValue",
       message: "Enum Value",
     });
     const description = translate({
-      id: OPENAPI_SCHEMA_ITEM.ENUM_DESCRIPTION,
+      id: "theme.openapi.schemaItem.enumDescription",
       message: "Description",
     });
     return `| ${enumValue} | ${description} |
@@ -92,13 +91,19 @@ function ParamsItem({ param, ...rest }: Props) {
 
   const renderSchemaRequired = guard(required, () => (
     <span className="openapi-schema__required">
-      {translate({ id: OPENAPI_SCHEMA_ITEM.REQUIRED, message: "required" })}
+      {translate({
+        id: "theme.openapi.schemaItem.required",
+        message: "required",
+      })}
     </span>
   ));
 
   const renderDeprecated = guard(deprecated, () => (
     <span className="openapi-schema__deprecated">
-      {translate({ id: OPENAPI_SCHEMA_ITEM.DEPRECATED, message: "deprecated" })}
+      {translate({
+        id: "theme.openapi.schemaItem.deprecated",
+        message: "deprecated",
+      })}
     </span>
   ));
 
@@ -113,7 +118,7 @@ function ParamsItem({ param, ...rest }: Props) {
       return undefined;
     }
     const label = translate({
-      id: OPENAPI_SCHEMA_ITEM.CONSTANT_VALUE,
+      id: "theme.openapi.schemaItem.constantValue",
       message: "Constant value:",
     });
     return (
@@ -152,7 +157,7 @@ function ParamsItem({ param, ...rest }: Props) {
           <div>
             <strong>
               {translate({
-                id: OPENAPI_SCHEMA_ITEM.DEFAULT_VALUE,
+                id: "theme.openapi.schemaItem.defaultValue",
                 message: "Default value:",
               })}{" "}
             </strong>
@@ -166,7 +171,7 @@ function ParamsItem({ param, ...rest }: Props) {
         <div>
           <strong>
             {translate({
-              id: OPENAPI_SCHEMA_ITEM.DEFAULT_VALUE,
+              id: "theme.openapi.schemaItem.defaultValue",
               message: "Default value:",
             })}{" "}
           </strong>

package/src/theme/RequestSchema/index.tsx

@@ -18,10 +18,10 @@ import {
   ResponseExamples,
 } from "@theme/ResponseExamples";
 import SchemaNode from "@theme/Schema";
+import SchemaExpansionControl from "@theme/SchemaExpansion";
 import SchemaTabs from "@theme/SchemaTabs";
 import SkeletonLoader from "@theme/SkeletonLoader";
 import TabItem from "@theme/TabItem";
-import { OPENAPI_REQUEST, OPENAPI_SCHEMA_ITEM } from "@theme/translationIds";
 import type { MediaTypeObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
 
 interface Props {
@@ -77,24 +77,23 @@ const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
                       open={true}
                       style={style}
                       summary={
-                        <>
-                          <summary>
-                            <h3 className="openapi-markdown__details-summary-header-body">
-                              {translate({
-                                id: OPENAPI_REQUEST.BODY_TITLE,
-                                message: title,
-                              })}
-                              {body.required === true && (
-                                <span className="openapi-schema__required">
-                                  {translate({
-                                    id: OPENAPI_SCHEMA_ITEM.REQUIRED,
-                                    message: "required",
-                                  })}
-                                </span>
-                              )}
-                            </h3>
-                          </summary>
-                        </>
+                        <summary className="openapi-markdown__details-summary--with-control">
+                          <h3 className="openapi-markdown__details-summary-header-body">
+                            {translate({
+                              id: "theme.openapi.request.body.title",
+                              message: title,
+                            })}
+                            {body.required === true && (
+                              <span className="openapi-schema__required">
+                                {translate({
+                                  id: "theme.openapi.schemaItem.required",
+                                  message: "required",
+                                })}
+                              </span>
+                            )}
+                          </h3>
+                          <SchemaExpansionControl />
+                        </summary>
                       }
                     >
                       <div style={{ textAlign: "left", marginLeft: "1rem" }}>
@@ -164,27 +163,26 @@ const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
               open={true}
               style={style}
               summary={
-                <>
-                  <summary>
-                    <h3 className="openapi-markdown__details-summary-header-body">
-                      {translate({
-                        id: OPENAPI_REQUEST.BODY_TITLE,
-                        message: title,
-                      })}
-                      {firstBody.type === "array" && (
-                        <span style={{ opacity: "0.6" }}> array</span>
-                      )}
-                      {body.required && (
-                        <strong className="openapi-schema__required">
-                          {translate({
-                            id: OPENAPI_SCHEMA_ITEM.REQUIRED,
-                            message: "required",
-                          })}
-                        </strong>
-                      )}
-                    </h3>
-                  </summary>
-                </>
+                <summary className="openapi-markdown__details-summary--with-control">
+                  <h3 className="openapi-markdown__details-summary-header-body">
+                    {translate({
+                      id: "theme.openapi.request.body.title",
+                      message: title,
+                    })}
+                    {firstBody.type === "array" && (
+                      <span style={{ opacity: "0.6" }}> array</span>
+                    )}
+                    {body.required && (
+                      <strong className="openapi-schema__required">
+                        {translate({
+                          id: "theme.openapi.schemaItem.required",
+                          message: "required",
+                        })}
+                      </strong>
+                    )}
+                  </h3>
+                  <SchemaExpansionControl />
+                </summary>
               }
             >
               <div style={{ textAlign: "left", marginLeft: "1rem" }}>

package/src/theme/ResponseExamples/index.tsx

@@ -11,7 +11,6 @@ import { translate } from "@docusaurus/Translate";
 import CodeSamples from "@theme/CodeSamples";
 import Markdown from "@theme/Markdown";
 import TabItem from "@theme/TabItem";
-import { OPENAPI_RESPONSE_EXAMPLES } from "@theme/translationIds";
 import { sampleResponseFromSchema } from "docusaurus-plugin-openapi-docs/lib/openapi/createResponseExample";
 import format from "xml-formatter";
 
@@ -115,7 +114,7 @@ export const ResponseExample: React.FC<ResponseExampleProps> = ({
     // @ts-ignore
     <TabItem
       label={translate({
-        id: OPENAPI_RESPONSE_EXAMPLES.EXAMPLE,
+        id: "theme.openapi.responseExamples.example",
         message: "Example",
       })}
       value="Example"
@@ -173,7 +172,7 @@ export const ExampleFromSchema: React.FC<ExampleFromSchemaProps> = ({
         // @ts-ignore
         <TabItem
           label={translate({
-            id: OPENAPI_RESPONSE_EXAMPLES.AUTO_EXAMPLE,
+            id: "theme.openapi.responseExamples.autoExample",
             message: "Example (auto)",
           })}
           value="Example (auto)"
@@ -192,7 +191,7 @@ export const ExampleFromSchema: React.FC<ExampleFromSchemaProps> = ({
       // @ts-ignore
       <TabItem
         label={translate({
-          id: OPENAPI_RESPONSE_EXAMPLES.AUTO_EXAMPLE,
+          id: "theme.openapi.responseExamples.autoExample",
           message: "Example (auto)",
         })}
         value="Example (auto)"

package/src/theme/ResponseSchema/index.tsx

@@ -18,10 +18,10 @@ import {
   ResponseExamples,
 } from "@theme/ResponseExamples";
 import SchemaNode from "@theme/Schema";
+import SchemaExpansionControl from "@theme/SchemaExpansion";
 import SchemaTabs from "@theme/SchemaTabs";
 import SkeletonLoader from "@theme/SkeletonLoader";
 import TabItem from "@theme/TabItem";
-import { OPENAPI_SCHEMA, OPENAPI_SCHEMA_ITEM } from "@theme/translationIds";
 import type { MediaTypeObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
 
 interface Props {
@@ -71,7 +71,7 @@ const ResponseSchemaComponent: React.FC<Props> = ({
               <TabItem key={mimeType} label={mimeType} value={mimeType}>
                 <div>
                   {translate({
-                    id: OPENAPI_SCHEMA.NO_SCHEMA,
+                    id: "theme.openapi.schema.noSchema",
                     message: "No schema",
                   })}
                 </div>
@@ -91,21 +91,20 @@ const ResponseSchemaComponent: React.FC<Props> = ({
                     open={true}
                     style={style}
                     summary={
-                      <>
-                        <summary>
-                          <strong className="openapi-markdown__details-summary-response">
-                            {title}
-                            {body.required === true && (
-                              <span className="openapi-schema__required">
-                                {translate({
-                                  id: OPENAPI_SCHEMA_ITEM.REQUIRED,
-                                  message: "required",
-                                })}
-                              </span>
-                            )}
-                          </strong>
-                        </summary>
-                      </>
+                      <summary className="openapi-markdown__details-summary--with-control">
+                        <strong className="openapi-markdown__details-summary-response">
+                          {title}
+                          {body.required === true && (
+                            <span className="openapi-schema__required">
+                              {translate({
+                                id: "theme.openapi.schemaItem.required",
+                                message: "required",
+                              })}
+                            </span>
+                          )}
+                        </strong>
+                        <SchemaExpansionControl />
+                      </summary>
                     }
                   >
                     <div style={{ textAlign: "left", marginLeft: "1rem" }}>

package/src/theme/Schema/index.tsx

@@ -14,10 +14,14 @@ import { ClosingArrayBracket, OpeningArrayBracket } from "@theme/ArrayBrackets";
 import Details from "@theme/Details";
 import DiscriminatorTabs from "@theme/DiscriminatorTabs";
 import Markdown from "@theme/Markdown";
+import {
+  SchemaDepthProvider,
+  useSchemaDepth,
+  useSchemaExpansion,
+} from "@theme/SchemaExpansion";
 import SchemaItem from "@theme/SchemaItem";
 import SchemaTabs from "@theme/SchemaTabs";
 import TabItem from "@theme/TabItem";
-import { OPENAPI_SCHEMA_ITEM } from "@theme/translationIds";
 // eslint-disable-next-line import/no-extraneous-dependencies
 import { merge } from "allof-merge";
 import clsx from "clsx";
@@ -29,16 +33,107 @@ import type { SchemaObject } from "../../types.d";
 // eslint-disable-next-line import/no-extraneous-dependencies
 // const jsonSchemaMergeAllOf = require("json-schema-merge-allof");
 
+/**
+ * Strip `additionalProperties: false` from sibling allOf members so the
+ * strict-AND semantics of `allof-merge` don't collapse the result to an
+ * unsatisfiable empty schema.
+ *
+ * Per JSON Schema, two allOf members that each set `additionalProperties: false`
+ * with disjoint `properties` sets define an unsatisfiable schema (no value can
+ * satisfy both — each member rejects the other's properties). `allof-merge` is
+ * technically correct to drop all properties in that case, but it leaves the
+ * rendered schema blank.
+ *
+ * NSwag and Swashbuckle emit this pattern by default whenever a model uses
+ * inheritance/composition, so it's the dominant style for .NET-generated specs.
+ * Redoc, Swagger UI, and Stoplight all union the properties and ignore the
+ * conflicting flag — the approach this helper emulates by stripping the flag
+ * before delegating to `allof-merge`. The flag is render-irrelevant anyway:
+ * `additionalProperties: false` is treated identically to `undefined` by the
+ * AdditionalProperties component below (line ~641).
+ *
+ * Strips from every allOf member whenever the parent has ≥2 members. The
+ * collapse triggers symmetrically (both siblings strict) or asymmetrically
+ * (one strict member rejects another's properties as "additional"), so the
+ * presence of multiple members is the right gate. Single-member allOf is left
+ * alone — it can't conflict with anything.
+ *
+ * See https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/1119
+ * Mirrored in plugin: docusaurus-plugin-openapi-docs/src/markdown/createSchema.ts
+ */
+const stripConflictingAdditionalProps = (node: any): any => {
+  if (Array.isArray(node)) return node.map(stripConflictingAdditionalProps);
+  if (!node || typeof node !== "object") return node;
+
+  let working: any = node;
+  if (Array.isArray(node.allOf) && node.allOf.length > 1) {
+    const hasStrictMember = node.allOf.some(
+      (m: any) => m && m.additionalProperties === false
+    );
+    if (hasStrictMember) {
+      working = {
+        ...node,
+        allOf: node.allOf.map((m: any) => {
+          if (m && m.additionalProperties === false) {
+            const { additionalProperties: _drop, ...rest } = m;
+            return rest;
+          }
+          return m;
+        }),
+      };
+    }
+  }
+
+  const result: any = {};
+  for (const [k, v] of Object.entries(working)) {
+    result[k] = stripConflictingAdditionalProps(v);
+  }
+  return result;
+};
+
 const mergeAllOf = (allOf: any) => {
   const onMergeError = (msg: string) => {
     console.warn(msg);
   };
 
-  const mergedSchemas = merge(allOf, { onMergeError });
+  const mergedSchemas = merge(stripConflictingAdditionalProps(allOf), {
+    onMergeError,
+  });
 
   return mergedSchemas ?? {};
 };
 
+/**
+ * Fold sibling fields into each `oneOf`/`anyOf` branch via allOf-merge, so each
+ * branch is self-contained. Mirrors Redoc's `SchemaModel.initOneOf` behavior.
+ * Without this, when an `allOf` override redefines a nested property with
+ * `oneOf`, the merged schema ends up with both `properties` and `oneOf` as
+ * siblings — and the renderer prints the shared properties twice.
+ *
+ * See https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/1218
+ */
+const foldSiblingsIntoBranches = (schema: any): any => {
+  const branchKey = schema?.oneOf
+    ? "oneOf"
+    : schema?.anyOf
+      ? "anyOf"
+      : undefined;
+  if (!branchKey) return schema;
+
+  const branches = schema[branchKey];
+  if (!Array.isArray(branches) || branches.length === 0) return schema;
+
+  const siblings = { ...schema };
+  delete siblings[branchKey];
+  if (Object.keys(siblings).length === 0) return schema;
+
+  const folded = branches.map((branch: any) =>
+    mergeAllOf({ allOf: [siblings, branch] })
+  );
+
+  return { [branchKey]: folded };
+};
+
 /**
  * Recursively searches for a property in a schema, including nested
  * oneOf, anyOf, and allOf structures. This is needed for discriminators
@@ -165,7 +260,7 @@ const Summary: React.FC<SummaryProps> = ({
         {nullable && (
           <span className="openapi-schema__nullable">
             {translate({
-              id: OPENAPI_SCHEMA_ITEM.NULLABLE,
+              id: "theme.openapi.schemaItem.nullable",
               message: "nullable",
             })}
           </span>
@@ -173,7 +268,7 @@ const Summary: React.FC<SummaryProps> = ({
         {isRequired && (
           <span className="openapi-schema__required">
             {translate({
-              id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+              id: "theme.openapi.schemaItem.required",
               message: "required",
             })}
           </span>
@@ -181,7 +276,7 @@ const Summary: React.FC<SummaryProps> = ({
         {deprecated && (
           <span className="openapi-schema__deprecated">
             {translate({
-              id: OPENAPI_SCHEMA_ITEM.DEPRECATED,
+              id: "theme.openapi.schemaItem.deprecated",
               message: "deprecated",
             })}
           </span>
@@ -218,8 +313,8 @@ const AnyOneOf: React.FC<SchemaProps> = ({
   }
 
   const type = schema.oneOf
-    ? translate({ id: OPENAPI_SCHEMA_ITEM.ONE_OF, message: "oneOf" })
-    : translate({ id: OPENAPI_SCHEMA_ITEM.ANY_OF, message: "anyOf" });
+    ? translate({ id: "theme.openapi.schemaItem.oneOf", message: "oneOf" })
+    : translate({ id: "theme.openapi.schemaItem.anyOf", message: "anyOf" });
 
   // Generate a unique ID for this anyOf/oneOf to prevent tab value collisions
   const uniqueId = React.useMemo(
@@ -268,12 +363,12 @@ const AnyOneOf: React.FC<SchemaProps> = ({
           if (!label) {
             if (anyOneSchema.oneOf) {
               label = translate({
-                id: OPENAPI_SCHEMA_ITEM.ONE_OF,
+                id: "theme.openapi.schemaItem.oneOf",
                 message: "oneOf",
               });
             } else if (anyOneSchema.anyOf) {
               label = translate({
-                id: OPENAPI_SCHEMA_ITEM.ANY_OF,
+                id: "theme.openapi.schemaItem.anyOf",
                 message: "anyOf",
               });
             } else {
@@ -454,7 +549,7 @@ const PropertyDiscriminator: React.FC<SchemaEdgeProps> = ({
             {required && (
               <span className="openapi-schema__required">
                 {translate({
-                  id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+                  id: "theme.openapi.schemaItem.required",
                   message: "required",
                 })}
               </span>
@@ -676,10 +771,15 @@ const SchemaNodeDetails: React.FC<SchemaEdgeProps> = ({
   schemaType,
   schemaPath,
 }) => {
+  const depth = useSchemaDepth();
+  const { level } = useSchemaExpansion();
+  const defaultOpen = depth < level;
   return (
     <SchemaItem collapsible={true}>
       <Details
+        key={`level-${level}`}
         className="openapi-markdown__details"
+        open={defaultOpen}
         summary={
           <Summary
             name={name}
@@ -694,11 +794,13 @@ const SchemaNodeDetails: React.FC<SchemaEdgeProps> = ({
           {getQualifierMessage(schema) && (
             <MarkdownWrapper text={getQualifierMessage(schema)} />
           )}
-          <SchemaNode
-            schema={schema}
-            schemaType={schemaType}
-            schemaPath={schemaPath}
-          />
+          <SchemaDepthProvider depth={depth + 1}>
+            <SchemaNode
+              schema={schema}
+              schemaType={schemaType}
+              schemaPath={schemaPath}
+            />
+          </SchemaDepthProvider>
         </div>
       </Details>
     </SchemaItem>
@@ -725,17 +827,25 @@ const Items: React.FC<{
   const itemsSchemaPath = schemaPath ? `${schemaPath}.items` : undefined;
 
   if (hasOneOfAnyOf || hasProperties || hasAdditionalProperties) {
+    // Fold sibling properties into each oneOf/anyOf branch to avoid duplicate
+    // property rendering. See issue #1218.
+    const renderSchema =
+      hasOneOfAnyOf && hasProperties
+        ? foldSiblingsIntoBranches(itemsSchema)
+        : itemsSchema;
+    const renderHasProperties =
+      hasOneOfAnyOf && hasProperties ? false : hasProperties;
     return (
       <>
         <OpeningArrayBracket />
         {hasOneOfAnyOf && (
           <AnyOneOf
-            schema={itemsSchema}
+            schema={renderSchema}
             schemaType={schemaType}
             schemaPath={itemsSchemaPath}
           />
         )}
-        {hasProperties && (
+        {renderHasProperties && (
           <Properties
             schema={itemsSchema}
             schemaType={schemaType}
@@ -1020,23 +1130,31 @@ function renderChildren(
   schemaType: "request" | "response",
   schemaPath?: string
 ) {
+  // Fold sibling properties into each oneOf/anyOf branch to avoid duplicate
+  // property rendering. See issue #1218.
+  const hasOneOfAnyOf = !!(schema.oneOf || schema.anyOf);
+  const hasProperties = !!schema.properties;
+  const folded =
+    hasOneOfAnyOf && hasProperties ? foldSiblingsIntoBranches(schema) : schema;
+  const renderProperties =
+    hasOneOfAnyOf && hasProperties ? false : hasProperties;
   return (
     <>
-      {schema.oneOf && (
+      {folded.oneOf && (
         <AnyOneOf
-          schema={schema}
+          schema={folded}
           schemaType={schemaType}
           schemaPath={schemaPath}
         />
       )}
-      {schema.anyOf && (
+      {folded.anyOf && (
         <AnyOneOf
-          schema={schema}
+          schema={folded}
           schemaType={schemaType}
           schemaPath={schemaPath}
         />
       )}
-      {schema.properties && (
+      {renderProperties && (
         <Properties
           schema={schema}
           schemaType={schemaType}
@@ -1160,23 +1278,34 @@ const SchemaNode: React.FC<SchemaProps> = ({
       return null;
     }
 
+    // Fold sibling properties into each oneOf/anyOf branch to avoid duplicate
+    // property rendering. See issue #1218.
+    const hasOneOfAnyOf = !!(mergedSchemas.oneOf || mergedSchemas.anyOf);
+    const hasProperties = !!mergedSchemas.properties;
+    const folded =
+      hasOneOfAnyOf && hasProperties
+        ? foldSiblingsIntoBranches(mergedSchemas)
+        : mergedSchemas;
+    const renderProperties =
+      hasOneOfAnyOf && hasProperties ? false : hasProperties;
+
     return (
       <div>
-        {mergedSchemas.oneOf && (
+        {folded.oneOf && (
           <AnyOneOf
-            schema={mergedSchemas}
+            schema={folded}
             schemaType={schemaType}
             schemaPath={schemaPath}
           />
         )}
-        {mergedSchemas.anyOf && (
+        {folded.anyOf && (
           <AnyOneOf
-            schema={mergedSchemas}
+            schema={folded}
             schemaType={schemaType}
             schemaPath={schemaPath}
           />
         )}
-        {mergedSchemas.properties && (
+        {renderProperties && (
           <Properties
             schema={mergedSchemas}
             schemaType={schemaType}