docusaurus-theme-openapi-docs 4.7.1 → 5.0.0

package/lib/theme/ParamsItem/index.js

@@ -88,11 +88,37 @@ function ParamsItem({ param, ...rest }) {
       })
     )
   );
+  const constValue = schema?.const;
   const renderQualifier = (0, utils_1.guard)(
     (0, schema_1.getQualifierMessage)(schema),
     (qualifier) =>
       react_1.default.createElement(Markdown_1.default, null, qualifier)
   );
+  function renderConstValue() {
+    if (constValue === undefined) {
+      return undefined;
+    }
+    const label = (0, Translate_1.translate)({
+      id: translationIds_1.OPENAPI_SCHEMA_ITEM.CONSTANT_VALUE,
+      message: "Constant value:",
+    });
+    return react_1.default.createElement(
+      "div",
+      null,
+      react_1.default.createElement("strong", null, label, " "),
+      react_1.default.createElement(
+        "span",
+        null,
+        react_1.default.createElement(
+          "code",
+          null,
+          typeof constValue === "string"
+            ? constValue
+            : JSON.stringify(constValue)
+        )
+      )
+    );
+  }
   const renderDescription = (0, utils_1.guard)(description, (description) =>
     react_1.default.createElement(Markdown_1.default, null, description)
   );
@@ -177,6 +203,7 @@ function ParamsItem({ param, ...rest }) {
       renderDeprecated
     ),
     renderQualifier,
+    renderConstValue(),
     renderDescription,
     renderEnumDescriptions,
     renderDefaultValue(),

package/lib/theme/RequestSchema/index.js

@@ -17,7 +17,9 @@ const Translate_1 = require("@docusaurus/Translate");
 const Details_1 = __importDefault(require("@theme/Details"));
 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 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");
@@ -36,7 +38,10 @@ const RequestSchemaComponent = ({ title, body, style }) => {
       MimeTabs_1.default,
       { className: "openapi-tabs__mime", schemaType: "request", lazy: true },
       mimeTypes.map((mimeType) => {
-        const firstBody = body.content[mimeType].schema;
+        const mediaTypeObject = body.content[mimeType];
+        const firstBody = mediaTypeObject?.schema;
+        const requestExamples = mediaTypeObject?.examples;
+        const requestExample = mediaTypeObject?.example;
         if (
           firstBody === undefined ||
           (firstBody.properties &&
@@ -50,68 +55,96 @@ const RequestSchemaComponent = ({ title, body, style }) => {
             TabItem_1.default,
             { key: mimeType, label: mimeType, value: mimeType },
             react_1.default.createElement(
-              "div",
-              { style: { marginTop: "1rem" } },
+              SchemaTabs_1.default,
+              { className: "openapi-tabs__schema" },
               react_1.default.createElement(
-                Details_1.default,
-                {
-                  className: "openapi-markdown__details mime",
-                  "data-collapsed": false,
-                  open: true,
-                  style: style,
-                  summary: react_1.default.createElement(
-                    react_1.default.Fragment,
-                    null,
-                    react_1.default.createElement(
-                      "summary",
-                      null,
-                      react_1.default.createElement(
-                        "h3",
-                        {
-                          className:
-                            "openapi-markdown__details-summary-header-body",
-                        },
-                        (0, Translate_1.translate)({
-                          id: translationIds_1.OPENAPI_REQUEST.BODY_TITLE,
-                          message: title,
-                        }),
-                        body.required === true &&
+                TabItem_1.default,
+                { key: title, label: title, value: title },
+                react_1.default.createElement(
+                  "div",
+                  { style: { marginTop: "1rem" } },
+                  react_1.default.createElement(
+                    Details_1.default,
+                    {
+                      className: "openapi-markdown__details mime",
+                      "data-collapsed": false,
+                      open: true,
+                      style: style,
+                      summary: react_1.default.createElement(
+                        react_1.default.Fragment,
+                        null,
+                        react_1.default.createElement(
+                          "summary",
+                          null,
                           react_1.default.createElement(
-                            "span",
-                            { className: "openapi-schema__required" },
+                            "h3",
+                            {
+                              className:
+                                "openapi-markdown__details-summary-header-body",
+                            },
                             (0, Translate_1.translate)({
-                              id: translationIds_1.OPENAPI_SCHEMA_ITEM.REQUIRED,
-                              message: "required",
-                            })
+                              id: translationIds_1.OPENAPI_REQUEST.BODY_TITLE,
+                              message: 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",
+                                })
+                              )
                           )
-                      )
-                    )
-                  ),
-                },
-                react_1.default.createElement(
-                  "div",
-                  { style: { textAlign: "left", marginLeft: "1rem" } },
-                  body.description &&
+                        )
+                      ),
+                    },
                     react_1.default.createElement(
                       "div",
-                      { style: { marginTop: "1rem", marginBottom: "1rem" } },
-                      react_1.default.createElement(
-                        Markdown_1.default,
-                        null,
-                        body.description
-                      )
+                      { style: { textAlign: "left", marginLeft: "1rem" } },
+                      body.description &&
+                        react_1.default.createElement(
+                          "div",
+                          {
+                            style: { marginTop: "1rem", marginBottom: "1rem" },
+                          },
+                          react_1.default.createElement(
+                            Markdown_1.default,
+                            null,
+                            body.description
+                          )
+                        )
+                    ),
+                    react_1.default.createElement(
+                      "ul",
+                      { style: { marginLeft: "1rem" } },
+                      react_1.default.createElement(Schema_1.default, {
+                        schema: firstBody,
+                        schemaType: "request",
+                        schemaPath: "requestBody",
+                      })
                     )
-                ),
-                react_1.default.createElement(
-                  "ul",
-                  { style: { marginLeft: "1rem" } },
-                  react_1.default.createElement(Schema_1.default, {
-                    schema: firstBody,
-                    schemaType: "request",
-                    schemaPath: "requestBody",
-                  })
+                  )
                 )
-              )
+              ),
+              firstBody &&
+                !requestExample &&
+                !requestExamples &&
+                (0, ResponseExamples_1.ExampleFromSchema)({
+                  schema: firstBody,
+                  mimeType: mimeType,
+                }),
+              requestExamples &&
+                (0, ResponseExamples_1.ResponseExamples)({
+                  responseExamples: requestExamples,
+                  mimeType,
+                }),
+              requestExample &&
+                (0, ResponseExamples_1.ResponseExample)({
+                  responseExample: requestExample,
+                  mimeType,
+                })
             )
           )
         );
@@ -119,8 +152,10 @@ const RequestSchemaComponent = ({ title, body, style }) => {
     );
   }
   const randomFirstKey = mimeTypes[0];
-  const firstBody =
-    body.content[randomFirstKey].schema ?? body.content[randomFirstKey];
+  const mediaTypeObject = body.content[randomFirstKey];
+  const firstBody = mediaTypeObject?.schema ?? body.content[randomFirstKey];
+  const requestExamples = mediaTypeObject?.examples;
+  const requestExample = mediaTypeObject?.example;
   if (firstBody === undefined) {
     return null;
   }
@@ -131,67 +166,95 @@ const RequestSchemaComponent = ({ title, body, style }) => {
       TabItem_1.default,
       { label: randomFirstKey, value: `${randomFirstKey}-schema` },
       react_1.default.createElement(
-        Details_1.default,
-        {
-          className: "openapi-markdown__details mime",
-          "data-collapsed": false,
-          open: true,
-          style: style,
-          summary: react_1.default.createElement(
-            react_1.default.Fragment,
-            null,
-            react_1.default.createElement(
-              "summary",
-              null,
-              react_1.default.createElement(
-                "h3",
-                { className: "openapi-markdown__details-summary-header-body" },
-                (0, Translate_1.translate)({
-                  id: translationIds_1.OPENAPI_REQUEST.BODY_TITLE,
-                  message: title,
-                }),
-                firstBody.type === "array" &&
-                  react_1.default.createElement(
-                    "span",
-                    { style: { opacity: "0.6" } },
-                    " array"
-                  ),
-                body.required &&
+        SchemaTabs_1.default,
+        { className: "openapi-tabs__schema" },
+        react_1.default.createElement(
+          TabItem_1.default,
+          { key: title, label: title, value: title },
+          react_1.default.createElement(
+            Details_1.default,
+            {
+              className: "openapi-markdown__details mime",
+              "data-collapsed": false,
+              open: true,
+              style: style,
+              summary: react_1.default.createElement(
+                react_1.default.Fragment,
+                null,
+                react_1.default.createElement(
+                  "summary",
+                  null,
                   react_1.default.createElement(
-                    "strong",
-                    { className: "openapi-schema__required" },
+                    "h3",
+                    {
+                      className:
+                        "openapi-markdown__details-summary-header-body",
+                    },
                     (0, Translate_1.translate)({
-                      id: translationIds_1.OPENAPI_SCHEMA_ITEM.REQUIRED,
-                      message: "required",
-                    })
+                      id: translationIds_1.OPENAPI_REQUEST.BODY_TITLE,
+                      message: title,
+                    }),
+                    firstBody.type === "array" &&
+                      react_1.default.createElement(
+                        "span",
+                        { style: { opacity: "0.6" } },
+                        " array"
+                      ),
+                    body.required &&
+                      react_1.default.createElement(
+                        "strong",
+                        { className: "openapi-schema__required" },
+                        (0, Translate_1.translate)({
+                          id: translationIds_1.OPENAPI_SCHEMA_ITEM.REQUIRED,
+                          message: "required",
+                        })
+                      )
                   )
-              )
-            )
-          ),
-        },
-        react_1.default.createElement(
-          "div",
-          { style: { textAlign: "left", marginLeft: "1rem" } },
-          body.description &&
+                )
+              ),
+            },
             react_1.default.createElement(
               "div",
-              { style: { marginTop: "1rem", marginBottom: "1rem" } },
-              react_1.default.createElement(
-                Markdown_1.default,
-                null,
-                body.description
-              )
+              { style: { textAlign: "left", marginLeft: "1rem" } },
+              body.description &&
+                react_1.default.createElement(
+                  "div",
+                  { style: { marginTop: "1rem", marginBottom: "1rem" } },
+                  react_1.default.createElement(
+                    Markdown_1.default,
+                    null,
+                    body.description
+                  )
+                )
+            ),
+            react_1.default.createElement(
+              "ul",
+              { style: { marginLeft: "1rem" } },
+              react_1.default.createElement(Schema_1.default, {
+                schema: firstBody,
+                schemaType: "request",
+                schemaPath: "requestBody",
+              })
             )
+          )
         ),
-        react_1.default.createElement(
-          "ul",
-          { style: { marginLeft: "1rem" } },
-          react_1.default.createElement(Schema_1.default, {
+        firstBody &&
+          !requestExample &&
+          !requestExamples &&
+          (0, ResponseExamples_1.ExampleFromSchema)({
             schema: firstBody,
-            schemaType: "request",
-            schemaPath: "requestBody",
+            mimeType: randomFirstKey,
+          }),
+        requestExamples &&
+          (0, ResponseExamples_1.ResponseExamples)({
+            responseExamples: requestExamples,
+            mimeType: randomFirstKey,
+          }),
+        requestExample &&
+          (0, ResponseExamples_1.ResponseExample)({
+            responseExample: requestExample,
+            mimeType: randomFirstKey,
           })
-        )
       )
     )
   );

package/lib/theme/ResponseHeaders/index.js

@@ -27,7 +27,6 @@ const ResponseHeaders = ({ responseHeaders }) => {
         name: name,
         collapsible: false,
         schemaName: (0, schema_1.getSchemaName)(schema),
-        qualifierMessage: (0, schema_1.getQualifierMessage)(schema),
         schema: schema,
         discriminator: false,
         children: null,

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

@@ -1,5 +1,5 @@
 import React from "react";
-import type { SchemaObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+import type { SchemaObject } from "../../types.d";
 interface SchemaProps {
     schema: SchemaObject;
     schemaType: "request" | "response";

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;