docusaurus-theme-openapi-docs 5.0.1 → 5.1.0

package/lib/theme/ResponseSchema/index.js

@@ -19,10 +19,10 @@ const Markdown_1 = __importDefault(require("@theme/Markdown"));
 const MimeTabs_1 = __importDefault(require("@theme/MimeTabs")); // Assume these components exist
 const ResponseExamples_1 = require("@theme/ResponseExamples");
 const Schema_1 = __importDefault(require("@theme/Schema"));
+const SchemaExpansion_1 = __importDefault(require("@theme/SchemaExpansion"));
 const SchemaTabs_1 = __importDefault(require("@theme/SchemaTabs"));
 const SkeletonLoader_1 = __importDefault(require("@theme/SkeletonLoader"));
 const TabItem_1 = __importDefault(require("@theme/TabItem"));
-const translationIds_1 = require("@theme/translationIds");
 const ResponseSchemaComponent = ({ title, body, style }) => {
   if (
     body === undefined ||
@@ -57,7 +57,7 @@ const ResponseSchemaComponent = ({ title, body, style }) => {
                 "div",
                 null,
                 (0, Translate_1.translate)({
-                  id: translationIds_1.OPENAPI_SCHEMA.NO_SCHEMA,
+                  id: "theme.openapi.schema.noSchema",
                   message: "No schema",
                 })
               )
@@ -83,29 +83,31 @@ const ResponseSchemaComponent = ({ title, body, style }) => {
                     open: true,
                     style: style,
                     summary: react_1.default.createElement(
-                      react_1.default.Fragment,
-                      null,
+                      "summary",
+                      {
+                        className:
+                          "openapi-markdown__details-summary--with-control",
+                      },
                       react_1.default.createElement(
-                        "summary",
-                        null,
-                        react_1.default.createElement(
-                          "strong",
-                          {
-                            className:
-                              "openapi-markdown__details-summary-response",
-                          },
-                          title,
-                          body.required === true &&
-                            react_1.default.createElement(
-                              "span",
-                              { className: "openapi-schema__required" },
-                              (0, Translate_1.translate)({
-                                id: translationIds_1.OPENAPI_SCHEMA_ITEM
-                                  .REQUIRED,
-                                message: "required",
-                              })
-                            )
-                        )
+                        "strong",
+                        {
+                          className:
+                            "openapi-markdown__details-summary-response",
+                        },
+                        title,
+                        body.required === true &&
+                          react_1.default.createElement(
+                            "span",
+                            { className: "openapi-schema__required" },
+                            (0, Translate_1.translate)({
+                              id: "theme.openapi.schemaItem.required",
+                              message: "required",
+                            })
+                          )
+                      ),
+                      react_1.default.createElement(
+                        SchemaExpansion_1.default,
+                        null
                       )
                     ),
                   },

package/lib/theme/Schema/index.js

@@ -77,10 +77,10 @@ const DiscriminatorTabs_1 = __importDefault(
   require("@theme/DiscriminatorTabs")
 );
 const Markdown_1 = __importDefault(require("@theme/Markdown"));
+const SchemaExpansion_1 = require("@theme/SchemaExpansion");
 const SchemaItem_1 = __importDefault(require("@theme/SchemaItem"));
 const SchemaTabs_1 = __importDefault(require("@theme/SchemaTabs"));
 const TabItem_1 = __importDefault(require("@theme/TabItem"));
-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"));
@@ -88,13 +88,99 @@ 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");
+/**
+ * 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) => {
+  if (Array.isArray(node)) return node.map(stripConflictingAdditionalProps);
+  if (!node || typeof node !== "object") return node;
+  let working = node;
+  if (Array.isArray(node.allOf) && node.allOf.length > 1) {
+    const hasStrictMember = node.allOf.some(
+      (m) => m && m.additionalProperties === false
+    );
+    if (hasStrictMember) {
+      working = {
+        ...node,
+        allOf: node.allOf.map((m) => {
+          if (m && m.additionalProperties === false) {
+            const { additionalProperties: _drop, ...rest } = m;
+            return rest;
+          }
+          return m;
+        }),
+      };
+    }
+  }
+  const result = {};
+  for (const [k, v] of Object.entries(working)) {
+    result[k] = stripConflictingAdditionalProps(v);
+  }
+  return result;
+};
 const mergeAllOf = (allOf) => {
   const onMergeError = (msg) => {
     console.warn(msg);
   };
-  const mergedSchemas = (0, allof_merge_1.merge)(allOf, { onMergeError });
+  const mergedSchemas = (0, allof_merge_1.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) => {
+  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) =>
+    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
@@ -199,7 +285,7 @@ const Summary = ({ name, schemaName, schema, required }) => {
           "span",
           { className: "openapi-schema__nullable" },
           (0, Translate_1.translate)({
-            id: translationIds_1.OPENAPI_SCHEMA_ITEM.NULLABLE,
+            id: "theme.openapi.schemaItem.nullable",
             message: "nullable",
           })
         ),
@@ -208,7 +294,7 @@ const Summary = ({ name, schemaName, schema, required }) => {
           "span",
           { className: "openapi-schema__required" },
           (0, Translate_1.translate)({
-            id: translationIds_1.OPENAPI_SCHEMA_ITEM.REQUIRED,
+            id: "theme.openapi.schemaItem.required",
             message: "required",
           })
         ),
@@ -217,7 +303,7 @@ const Summary = ({ name, schemaName, schema, required }) => {
           "span",
           { className: "openapi-schema__deprecated" },
           (0, Translate_1.translate)({
-            id: translationIds_1.OPENAPI_SCHEMA_ITEM.DEPRECATED,
+            id: "theme.openapi.schemaItem.deprecated",
             message: "deprecated",
           })
         )
@@ -234,11 +320,11 @@ const AnyOneOf = ({ schema, schemaType, schemaPath }) => {
   }
   const type = schema.oneOf
     ? (0, Translate_1.translate)({
-        id: translationIds_1.OPENAPI_SCHEMA_ITEM.ONE_OF,
+        id: "theme.openapi.schemaItem.oneOf",
         message: "oneOf",
       })
     : (0, Translate_1.translate)({
-        id: translationIds_1.OPENAPI_SCHEMA_ITEM.ANY_OF,
+        id: "theme.openapi.schemaItem.anyOf",
         message: "anyOf",
       });
   // Generate a unique ID for this anyOf/oneOf to prevent tab value collisions
@@ -285,12 +371,12 @@ const AnyOneOf = ({ schema, schemaType, schemaPath }) => {
         if (!label) {
           if (anyOneSchema.oneOf) {
             label = (0, Translate_1.translate)({
-              id: translationIds_1.OPENAPI_SCHEMA_ITEM.ONE_OF,
+              id: "theme.openapi.schemaItem.oneOf",
               message: "oneOf",
             });
           } else if (anyOneSchema.anyOf) {
             label = (0, Translate_1.translate)({
-              id: translationIds_1.OPENAPI_SCHEMA_ITEM.ANY_OF,
+              id: "theme.openapi.schemaItem.anyOf",
               message: "anyOf",
             });
           } else {
@@ -459,7 +545,7 @@ const PropertyDiscriminator = ({
               "span",
               { className: "openapi-schema__required" },
               (0, Translate_1.translate)({
-                id: translationIds_1.OPENAPI_SCHEMA_ITEM.REQUIRED,
+                id: "theme.openapi.schemaItem.required",
                 message: "required",
               })
             )
@@ -644,13 +730,18 @@ const SchemaNodeDetails = ({
   schemaType,
   schemaPath,
 }) => {
+  const depth = (0, SchemaExpansion_1.useSchemaDepth)();
+  const { level } = (0, SchemaExpansion_1.useSchemaExpansion)();
+  const defaultOpen = depth < level;
   return react_1.default.createElement(
     SchemaItem_1.default,
     { collapsible: true },
     react_1.default.createElement(
       Details_1.default,
       {
+        key: `level-${level}`,
         className: "openapi-markdown__details",
+        open: defaultOpen,
         summary: react_1.default.createElement(Summary, {
           name: name,
           schemaName: schemaName,
@@ -669,11 +760,15 @@ const SchemaNodeDetails = ({
           react_1.default.createElement(MarkdownWrapper, {
             text: (0, schema_1.getQualifierMessage)(schema),
           }),
-        react_1.default.createElement(SchemaNode, {
-          schema: schema,
-          schemaType: schemaType,
-          schemaPath: schemaPath,
-        })
+        react_1.default.createElement(
+          SchemaExpansion_1.SchemaDepthProvider,
+          { depth: depth + 1 },
+          react_1.default.createElement(SchemaNode, {
+            schema: schema,
+            schemaType: schemaType,
+            schemaPath: schemaPath,
+          })
+        )
       )
     )
   );
@@ -691,17 +786,25 @@ const Items = ({ schema, schemaType, schemaPath }) => {
   // Build the items schema path
   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 react_1.default.createElement(
       react_1.default.Fragment,
       null,
       react_1.default.createElement(ArrayBrackets_1.OpeningArrayBracket, null),
       hasOneOfAnyOf &&
         react_1.default.createElement(AnyOneOf, {
-          schema: itemsSchema,
+          schema: renderSchema,
           schemaType: schemaType,
           schemaPath: itemsSchemaPath,
         }),
-      hasProperties &&
+      renderHasProperties &&
         react_1.default.createElement(Properties, {
           schema: itemsSchema,
           schemaType: schemaType,
@@ -918,22 +1021,30 @@ const SchemaEdge = ({
   });
 };
 function renderChildren(schema, schemaType, schemaPath) {
+  // 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 react_1.default.createElement(
     react_1.default.Fragment,
     null,
-    schema.oneOf &&
+    folded.oneOf &&
       react_1.default.createElement(AnyOneOf, {
-        schema: schema,
+        schema: folded,
         schemaType: schemaType,
         schemaPath: schemaPath,
       }),
-    schema.anyOf &&
+    folded.anyOf &&
       react_1.default.createElement(AnyOneOf, {
-        schema: schema,
+        schema: folded,
         schemaType: schemaType,
         schemaPath: schemaPath,
       }),
-    schema.properties &&
+    renderProperties &&
       react_1.default.createElement(Properties, {
         schema: schema,
         schemaType: schemaType,
@@ -1034,22 +1145,32 @@ const SchemaNode = ({ schema, schemaType, schemaPath }) => {
     ) {
       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 react_1.default.createElement(
       "div",
       null,
-      mergedSchemas.oneOf &&
+      folded.oneOf &&
         react_1.default.createElement(AnyOneOf, {
-          schema: mergedSchemas,
+          schema: folded,
           schemaType: schemaType,
           schemaPath: schemaPath,
         }),
-      mergedSchemas.anyOf &&
+      folded.anyOf &&
         react_1.default.createElement(AnyOneOf, {
-          schema: mergedSchemas,
+          schema: folded,
           schemaType: schemaType,
           schemaPath: schemaPath,
         }),
-      mergedSchemas.properties &&
+      renderProperties &&
         react_1.default.createElement(Properties, {
           schema: mergedSchemas,
           schemaType: schemaType,

package/lib/theme/SchemaExpansion/_SchemaExpansion.scss

@@ -0,0 +1,113 @@
+/* ============================================================================
+ * Copyright (c) Palo Alto Networks
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ * ========================================================================== */
+
+.openapi-schema-expansion {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  margin-left: auto;
+}
+
+.openapi-schema-expansion__trigger {
+  appearance: none;
+  background: transparent;
+  border: none;
+  border-radius: var(--ifm-global-radius);
+  padding: 0;
+  width: 22px;
+  height: 22px;
+  flex: 0 0 22px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--ifm-color-emphasis-600);
+  line-height: 0;
+  opacity: 0.7;
+  transition:
+    opacity 0.12s ease,
+    background-color 0.12s ease,
+    color 0.12s ease;
+
+  &:hover {
+    opacity: 1;
+    background-color: var(--ifm-color-emphasis-200);
+    color: var(--ifm-color-emphasis-900);
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--ifm-color-primary);
+    outline-offset: 2px;
+    opacity: 1;
+  }
+
+  &[aria-expanded="true"] {
+    opacity: 1;
+    background-color: var(--ifm-color-emphasis-200);
+    color: var(--ifm-color-emphasis-900);
+  }
+}
+
+.openapi-schema-expansion__popover {
+  position: fixed;
+  z-index: 1000;
+  display: inline-flex;
+  align-items: center;
+  gap: 2px;
+  padding: 3px;
+  background-color: var(--ifm-background-surface-color);
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: var(--ifm-global-radius);
+  box-shadow: var(--ifm-global-shadow-md);
+  white-space: nowrap;
+}
+
+.openapi-schema-expansion__option {
+  appearance: none;
+  background: transparent;
+  border: none;
+  border-radius: calc(var(--ifm-global-radius) - 2px);
+  padding: 2px 8px;
+  font-size: 0.8rem;
+  line-height: 1.4;
+  color: var(--ifm-color-emphasis-800);
+  transition:
+    background-color 0.12s ease,
+    color 0.12s ease;
+
+  &:hover {
+    background-color: var(--ifm-color-emphasis-200);
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--ifm-color-primary);
+    outline-offset: 1px;
+  }
+}
+
+.openapi-schema-expansion__option--active {
+  background-color: var(--ifm-color-primary);
+  color: var(--ifm-color-white);
+
+  &:hover {
+    background-color: var(--ifm-color-primary-dark);
+  }
+}
+
+.openapi-markdown__details-summary--with-control {
+  display: flex !important;
+  align-items: center;
+  gap: 0.5rem;
+
+  > h3,
+  > strong {
+    margin-bottom: 0;
+    display: inline-flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: 0.4rem;
+  }
+}

package/lib/theme/SchemaExpansion/context.d.ts

@@ -0,0 +1,24 @@
+import React from "react";
+export declare const SCHEMA_EXPANSION_STORAGE_KEY = "docusaurus-openapi-schema-expansion-level";
+export interface SchemaExpansionConfig {
+    enabled: boolean;
+    defaultLevel: number;
+    max: number;
+    persist: boolean;
+}
+interface SchemaExpansionContextValue {
+    config: SchemaExpansionConfig;
+    level: number;
+    setLevel: (next: number) => void;
+}
+export declare function normalizeLevel(value: number | "all" | undefined): number;
+export declare const SchemaExpansionProvider: React.FC<{
+    children: React.ReactNode;
+}>;
+export declare const SchemaDepthProvider: React.FC<{
+    depth: number;
+    children: React.ReactNode;
+}>;
+export declare function useSchemaExpansion(): SchemaExpansionContextValue;
+export declare function useSchemaDepth(): number;
+export {};