docusaurus-theme-openapi-docs 4.5.0 → 4.6.0

package/src/theme/Schema/index.tsx

@@ -7,6 +7,7 @@
 
 import React from "react";
 
+import { translate } from "@docusaurus/Translate";
 import { ClosingArrayBracket, OpeningArrayBracket } from "@theme/ArrayBrackets";
 import Details from "@theme/Details";
 import DiscriminatorTabs from "@theme/DiscriminatorTabs";
@@ -14,6 +15,7 @@ import Markdown from "@theme/Markdown";
 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";
@@ -89,12 +91,29 @@ const Summary: React.FC<SummaryProps> = ({
         {(isRequired || deprecated || nullable) && (
           <span className="openapi-schema__divider" />
         )}
-        {nullable && <span className="openapi-schema__nullable">nullable</span>}
+        {nullable && (
+          <span className="openapi-schema__nullable">
+            {translate({
+              id: OPENAPI_SCHEMA_ITEM.NULLABLE,
+              message: "nullable",
+            })}
+          </span>
+        )}
         {isRequired && (
-          <span className="openapi-schema__required">required</span>
+          <span className="openapi-schema__required">
+            {translate({
+              id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+              message: "required",
+            })}
+          </span>
         )}
         {deprecated && (
-          <span className="openapi-schema__deprecated">deprecated</span>
+          <span className="openapi-schema__deprecated">
+            {translate({
+              id: OPENAPI_SCHEMA_ITEM.DEPRECATED,
+              message: "deprecated",
+            })}
+          </span>
         )}
       </span>
     </summary>
@@ -108,28 +127,59 @@ interface SchemaProps {
 }
 
 const AnyOneOf: React.FC<SchemaProps> = ({ schema, schemaType }) => {
-  const type = schema.oneOf ? "oneOf" : "anyOf";
+  const key = schema.oneOf ? "oneOf" : "anyOf";
+  const type = schema.oneOf
+    ? translate({ id: OPENAPI_SCHEMA_ITEM.ONE_OF, message: "oneOf" })
+    : translate({ id: OPENAPI_SCHEMA_ITEM.ANY_OF, message: "anyOf" });
+
+  // Generate a unique ID for this anyOf/oneOf to prevent tab value collisions
+  const uniqueId = React.useMemo(
+    () => Math.random().toString(36).substring(7),
+    []
+  );
+
   return (
     <>
       <span className="badge badge--info" style={{ marginBottom: "1rem" }}>
         {type}
       </span>
-      <SchemaTabs>
-        {schema[type]?.map((anyOneSchema: any, index: number) => {
-          const label = anyOneSchema.title || anyOneSchema.type;
+      <SchemaTabs groupId={`schema-${uniqueId}`} lazy>
+        {schema[key]?.map((anyOneSchema: any, index: number) => {
+          // Use getSchemaName to include format info (e.g., "string<date-time>")
+          const computedSchemaName = getSchemaName(anyOneSchema);
+
+          // Determine label for the tab
+          // Prefer explicit title, then computed schema name, then raw type
+          let label =
+            anyOneSchema.title || computedSchemaName || anyOneSchema.type;
+          if (!label) {
+            if (anyOneSchema.oneOf) {
+              label = translate({
+                id: OPENAPI_SCHEMA_ITEM.ONE_OF,
+                message: "oneOf",
+              });
+            } else if (anyOneSchema.anyOf) {
+              label = translate({
+                id: OPENAPI_SCHEMA_ITEM.ANY_OF,
+                message: "anyOf",
+              });
+            } else {
+              label = `Option ${index + 1}`;
+            }
+          }
           return (
             // @ts-ignore
             <TabItem
               key={index}
               label={label}
-              value={`${index}-item-properties`}
+              value={`${uniqueId}-${index}-item`}
             >
               {/* Handle primitive types directly */}
               {(isPrimitive(anyOneSchema) || anyOneSchema.const) && (
                 <SchemaItem
                   collapsible={false}
                   name={undefined}
-                  schemaName={anyOneSchema.type}
+                  schemaName={computedSchemaName}
                   qualifierMessage={getQualifierMessage(anyOneSchema)}
                   schema={anyOneSchema}
                   discriminator={false}
@@ -146,7 +196,7 @@ const AnyOneOf: React.FC<SchemaProps> = ({ schema, schemaType }) => {
                   <SchemaItem
                     collapsible={false}
                     name={undefined}
-                    schemaName={anyOneSchema.type}
+                    schemaName={computedSchemaName}
                     qualifierMessage={getQualifierMessage(anyOneSchema)}
                     schema={anyOneSchema}
                     discriminator={false}
@@ -155,9 +205,11 @@ const AnyOneOf: React.FC<SchemaProps> = ({ schema, schemaType }) => {
                 )}
 
               {/* Handle actual object types with properties or nested schemas */}
-              {anyOneSchema.type === "object" && anyOneSchema.properties && (
-                <Properties schema={anyOneSchema} schemaType={schemaType} />
-              )}
+              {/* Note: In OpenAPI, properties implies type: object even if not explicitly set */}
+              {(anyOneSchema.type === "object" || !anyOneSchema.type) &&
+                anyOneSchema.properties && (
+                  <Properties schema={anyOneSchema} schemaType={schemaType} />
+                )}
               {anyOneSchema.allOf && (
                 <SchemaNode schema={anyOneSchema} schemaType={schemaType} />
               )}
@@ -254,7 +306,12 @@ const PropertyDiscriminator: React.FC<SchemaEdgeProps> = ({
             )}
             {required && <span className="openapi-schema__divider"></span>}
             {required && (
-              <span className="openapi-schema__required">required</span>
+              <span className="openapi-schema__required">
+                {translate({
+                  id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+                  message: "required",
+                })}
+              </span>
             )}
           </span>
           <div style={{ marginLeft: "1rem" }}>
@@ -672,7 +729,7 @@ const SchemaEdge: React.FC<SchemaEdgeProps> = ({
     );
   }
 
-  if (schema.items?.anyOf || schema.items?.oneOf) {
+  if (schema.items?.anyOf || schema.items?.oneOf || schema.items?.allOf) {
     return (
       <SchemaNodeDetails
         name={name}
@@ -725,9 +782,7 @@ const SchemaEdge: React.FC<SchemaEdgeProps> = ({
           name={name}
           schemaName={mergedSchemaName}
           required={
-            Array.isArray(mergedSchemas.required)
-              ? mergedSchemas.required.includes(name)
-              : mergedSchemas.required
+            Array.isArray(required) ? required.includes(name) : required
           }
           nullable={mergedSchemas.nullable}
           schema={mergedSchemas}
@@ -742,9 +797,7 @@ const SchemaEdge: React.FC<SchemaEdgeProps> = ({
           name={name}
           schemaName={mergedSchemaName}
           required={
-            Array.isArray(mergedSchemas.required)
-              ? mergedSchemas.required.includes(name)
-              : mergedSchemas.required
+            Array.isArray(required) ? required.includes(name) : required
           }
           nullable={mergedSchemas.nullable}
           schema={mergedSchemas}
@@ -754,18 +807,18 @@ const SchemaEdge: React.FC<SchemaEdgeProps> = ({
     }
 
     if (mergedSchemas.items?.properties) {
-      <SchemaNodeDetails
-        name={name}
-        schemaName={mergedSchemaName}
-        required={
-          Array.isArray(mergedSchemas.required)
-            ? mergedSchemas.required.includes(name)
-            : mergedSchemas.required
-        }
-        nullable={mergedSchemas.nullable}
-        schema={mergedSchemas}
-        schemaType={schemaType}
-      />;
+      return (
+        <SchemaNodeDetails
+          name={name}
+          schemaName={mergedSchemaName}
+          required={
+            Array.isArray(required) ? required.includes(name) : required
+          }
+          nullable={mergedSchemas.nullable}
+          schema={mergedSchemas}
+          schemaType={schemaType}
+        />
+      );
     }
 
     return (
@@ -836,6 +889,48 @@ const SchemaNode: React.FC<SchemaProps> = ({ schema, schemaType }) => {
 
   // Handle allOf, oneOf, anyOf without discriminators
   if (schema.allOf) {
+    // Check if allOf contains multiple oneOf/anyOf items that should be rendered separately
+    const oneOfItems = schema.allOf.filter(
+      (item: any) => item.oneOf || item.anyOf
+    );
+    const hasMultipleChoices = oneOfItems.length > 1;
+
+    if (hasMultipleChoices) {
+      // Render each oneOf/anyOf constraint first, then shared properties
+      const mergedSchemas = mergeAllOf(schema) as SchemaObject;
+
+      if (
+        (schemaType === "request" && mergedSchemas.readOnly) ||
+        (schemaType === "response" && mergedSchemas.writeOnly)
+      ) {
+        return null;
+      }
+
+      return (
+        <div>
+          {/* Render all oneOf/anyOf constraints first */}
+          {schema.allOf.map((item: any, index: number) => {
+            if (item.oneOf || item.anyOf) {
+              return (
+                <div key={index}>
+                  <AnyOneOf schema={item} schemaType={schemaType} />
+                </div>
+              );
+            }
+            return null;
+          })}
+          {/* Then render shared properties from the merge */}
+          {mergedSchemas.properties && (
+            <Properties schema={mergedSchemas} schemaType={schemaType} />
+          )}
+          {mergedSchemas.items && (
+            <Items schema={mergedSchemas} schemaType={schemaType} />
+          )}
+        </div>
+      );
+    }
+
+    // For other allOf cases, use standard merge behavior
     const mergedSchemas = mergeAllOf(schema) as SchemaObject;
 
     if (

package/src/theme/SchemaItem/index.tsx

@@ -7,7 +7,10 @@
 
 import React, { ReactNode } from "react";
 
+import { translate } from "@docusaurus/Translate";
+import { Example } from "@theme/Example";
 import Markdown from "@theme/Markdown";
+import { OPENAPI_SCHEMA_ITEM } from "@theme/translationIds";
 import clsx from "clsx";
 
 import { guard } from "../../markdown/utils";
@@ -36,7 +39,15 @@ const transformEnumDescriptions = (
 
 const getEnumDescriptionMarkdown = (enumDescriptions?: [string, string][]) => {
   if (enumDescriptions?.length) {
-    return `| Enum Value | Description |
+    const enumValue = translate({
+      id: OPENAPI_SCHEMA_ITEM.ENUM_VALUE,
+      message: "Enum Value",
+    });
+    const description = translate({
+      id: OPENAPI_SCHEMA_ITEM.ENUM_DESCRIPTION,
+      message: "Description",
+    });
+    return `| ${enumValue} | ${description} |
 | ---- | ----- |
 ${enumDescriptions
   .map((desc) => {
@@ -63,6 +74,7 @@ export default function SchemaItem(props: Props) {
   let schemaDescription;
   let defaultValue: string | undefined;
   let example: string | undefined;
+  let examples: string[] | undefined;
   let nullable;
   let enumDescriptions: [string, string][] = [];
   let constValue: string | undefined;
@@ -73,6 +85,7 @@ export default function SchemaItem(props: Props) {
     enumDescriptions = transformEnumDescriptions(schema["x-enumDescriptions"]);
     defaultValue = schema.default;
     example = schema.example;
+    examples = schema.examples;
     nullable =
       schema.nullable ||
       (Array.isArray(schema.type) && schema.type.includes("null")); // support JSON Schema nullable
@@ -81,15 +94,23 @@ export default function SchemaItem(props: Props) {
 
   const renderRequired = guard(
     Array.isArray(required) ? required.includes(name) : required,
-    () => <span className="openapi-schema__required">required</span>
+    () => (
+      <span className="openapi-schema__required">
+        {translate({ id: OPENAPI_SCHEMA_ITEM.REQUIRED, message: "required" })}
+      </span>
+    )
   );
 
   const renderDeprecated = guard(deprecated, () => (
-    <span className="openapi-schema__deprecated">deprecated</span>
+    <span className="openapi-schema__deprecated">
+      {translate({ id: OPENAPI_SCHEMA_ITEM.DEPRECATED, message: "deprecated" })}
+    </span>
   ));
 
   const renderNullable = guard(nullable, () => (
-    <span className="openapi-schema__nullable">nullable</span>
+    <span className="openapi-schema__nullable">
+      {translate({ id: OPENAPI_SCHEMA_ITEM.NULLABLE, message: "nullable" })}
+    </span>
   ));
 
   const renderEnumDescriptions = guard(
@@ -120,7 +141,12 @@ export default function SchemaItem(props: Props) {
       if (typeof defaultValue === "string") {
         return (
           <div>
-            <strong>Default value: </strong>
+            <strong>
+              {translate({
+                id: OPENAPI_SCHEMA_ITEM.DEFAULT_VALUE,
+                message: "Default value:",
+              })}{" "}
+            </strong>
             <span>
               <code>{defaultValue}</code>
             </span>
@@ -129,7 +155,12 @@ export default function SchemaItem(props: Props) {
       }
       return (
         <div>
-          <strong>Default value: </strong>
+          <strong>
+            {translate({
+              id: OPENAPI_SCHEMA_ITEM.DEFAULT_VALUE,
+              message: "Default value:",
+            })}{" "}
+          </strong>
           <span>
             <code>{JSON.stringify(defaultValue)}</code>
           </span>
@@ -139,36 +170,17 @@ export default function SchemaItem(props: Props) {
     return undefined;
   }
 
-  function renderExample() {
-    if (example !== undefined) {
-      if (typeof example === "string") {
-        return (
-          <div>
-            <strong>Example: </strong>
-            <span>
-              <code>{example}</code>
-            </span>
-          </div>
-        );
-      }
-      return (
-        <div>
-          <strong>Example: </strong>
-          <span>
-            <code>{JSON.stringify(example)}</code>
-          </span>
-        </div>
-      );
-    }
-    return undefined;
-  }
-
   function renderConstValue() {
     if (constValue !== undefined) {
       if (typeof constValue === "string") {
         return (
           <div>
-            <strong>Constant value: </strong>
+            <strong>
+              {translate({
+                id: OPENAPI_SCHEMA_ITEM.CONSTANT_VALUE,
+                message: "Constant value:",
+              })}{" "}
+            </strong>
             <span>
               <code>{constValue}</code>
             </span>
@@ -177,7 +189,12 @@ export default function SchemaItem(props: Props) {
       }
       return (
         <div>
-          <strong>Constant value: </strong>
+          <strong>
+            {translate({
+              id: OPENAPI_SCHEMA_ITEM.CONSTANT_VALUE,
+              message: "Constant value:",
+            })}{" "}
+          </strong>
           <span>
             <code>{JSON.stringify(constValue)}</code>
           </span>
@@ -212,7 +229,8 @@ export default function SchemaItem(props: Props) {
       {renderQualifierMessage}
       {renderConstValue()}
       {renderDefaultValue()}
-      {renderExample()}
+      <Example example={example} />
+      <Example examples={examples} />
       {collapsibleSchemaContent ?? collapsibleSchemaContent}
     </div>
   );

package/src/theme/SchemaTabs/index.tsx

@@ -115,7 +115,10 @@ function TabList({
   };
 
   return (
-    <div className="openapi-tabs__schema-tabs-container">
+    <div
+      className="openapi-tabs__schema-tabs-container"
+      style={{ marginBottom: "1rem" }}
+    >
       {showTabArrows && (
         <button
           className="openapi-tabs__arrow left"

package/src/theme/StatusCodes/index.tsx

@@ -7,12 +7,15 @@
 
 import React from "react";
 
+import { translate } from "@docusaurus/Translate";
+
 import ApiTabs from "@theme/ApiTabs";
 import Details from "@theme/Details";
 import Markdown from "@theme/Markdown";
 import ResponseHeaders from "@theme/ResponseHeaders";
 import ResponseSchema from "@theme/ResponseSchema";
 import TabItem from "@theme/TabItem";
+import { OPENAPI_STATUS_CODES } from "@theme/translationIds";
 import { ApiItem } from "docusaurus-plugin-openapi-docs/lib/types";
 
 interface Props {
@@ -51,7 +54,12 @@ const StatusCodes: React.FC<Props> = ({ label, id, responses }: any) => {
                 style={{ textAlign: "left", marginBottom: "1rem" }}
                 summary={
                   <summary>
-                    <strong>Response Headers</strong>
+                    <strong>
+                      {translate({
+                        id: OPENAPI_STATUS_CODES.RESPONSE_HEADERS,
+                        message: "Response Headers",
+                      })}
+                    </strong>
                   </summary>
                 }
               >
@@ -59,7 +67,10 @@ const StatusCodes: React.FC<Props> = ({ label, id, responses }: any) => {
               </Details>
             )}
             <ResponseSchema
-              title="Schema"
+              title={translate({
+                id: OPENAPI_STATUS_CODES.SCHEMA_TITLE,
+                message: "Schema",
+              })}
               body={{ content: response.content }}
             />
           </TabItem>

package/src/theme/styles.scss

@@ -41,6 +41,8 @@
 @use "./CodeSamples/CodeSamples";
 /* Markdown Styling */
 @use "./Markdown/Details/Details";
+/* Example Styling */
+@use "./Example/Example";
 
 :root {
   --openapi-required: var(--ifm-color-danger);
@@ -67,6 +69,9 @@
   --openapi-code-tab-border-color-java: #0374bd;
   --openapi-code-tab-border-color-powershell: #00adef;
   --openapi-code-tab-shadow-color-python: rgba(255, 219, 80, 0.25);
+  --openapi-code-tab-shadow-color-curl: var(
+    --openapi-code-tab-shadow-color-bash
+  );
   --openapi-code-tab-shadow-color-bash: rgba(250, 56, 62, 0.25);
   --openapi-code-tab-shadow-color-go: rgba(84, 199, 236, 0.25);
   --openapi-code-tab-shadow-color-js: rgba(255, 186, 0, 0.25);

package/src/theme/translationIds.ts

@@ -0,0 +1,111 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+export const OPENAPI_RESPONSE = {
+  TITLE: "theme.openapi.response.title",
+  CLEAR: "theme.openapi.response.clear",
+  PLACEHOLDER: "theme.openapi.response.placeholder",
+  HEADERS_TAB: "theme.openapi.response.headersTab",
+};
+
+export const OPENAPI_TABS = {
+  RESPONSES_LABEL: "theme.openapi.tabs.responses.label",
+};
+
+export const OPENAPI_REQUEST = {
+  BODY_TITLE: "theme.openapi.request.body.title",
+  ACCEPT_TITLE: "theme.openapi.request.accept.title",
+  SEND_BUTTON: "theme.openapi.request.sendButton",
+  REQUIRED_LABEL: "theme.openapi.request.requiredLabel",
+  REQUEST_TITLE: "theme.openapi.request.title",
+  COLLAPSE_ALL: "theme.openapi.request.collapseAll",
+  EXPAND_ALL: "theme.openapi.request.expandAll",
+  BASE_URL_TITLE: "theme.openapi.request.baseUrl.title",
+  AUTH_TITLE: "theme.openapi.request.auth.title",
+  PARAMETERS_TITLE: "theme.openapi.request.parameters.title",
+  FETCHING_MESSAGE: "theme.openapi.request.fetchingMessage",
+  CONNECTION_FAILED: "theme.openapi.request.connectionFailed",
+  ERROR_TIMEOUT: "theme.openapi.request.error.timeout",
+  ERROR_NETWORK: "theme.openapi.request.error.network",
+  ERROR_CORS: "theme.openapi.request.error.cors",
+  ERROR_UNKNOWN: "theme.openapi.request.error.unknown",
+};
+
+export const OPENAPI_SERVER = {
+  EDIT_BUTTON: "theme.openapi.server.editButton",
+  HIDE_BUTTON: "theme.openapi.server.hideButton",
+};
+
+export const OPENAPI_PARAM_OPTIONS = {
+  SHOW_OPTIONAL: "theme.openapi.paramOptions.showOptional",
+  HIDE_OPTIONAL: "theme.openapi.paramOptions.hideOptional",
+};
+
+export const OPENAPI_FORM_FILE_UPLOAD = {
+  CLEAR_BUTTON: "theme.openapi.formFileUpload.clearButton",
+};
+
+export const OPENAPI_FORM = {
+  FIELD_REQUIRED: "theme.openapi.form.fieldRequired",
+};
+
+export const OPENAPI_AUTH = {
+  BEARER_TOKEN: "theme.openapi.auth.bearerToken",
+  USERNAME: "theme.openapi.auth.username",
+  PASSWORD: "theme.openapi.auth.password",
+  SECURITY_SCHEME: "theme.openapi.auth.securityScheme",
+};
+
+export const OPENAPI_RESPONSE_EXAMPLES = {
+  EXAMPLE: "theme.openapi.responseExamples.example",
+  AUTO_EXAMPLE: "theme.openapi.responseExamples.autoExample",
+};
+
+export const OPENAPI_BODY = {
+  EXAMPLE_FROM_SCHEMA: "theme.openapi.body.exampleFromSchema",
+};
+
+export const OPENAPI_STATUS_CODES = {
+  RESPONSE_HEADERS: "theme.openapi.statusCodes.responseHeaders",
+  SCHEMA_TITLE: "theme.openapi.statusCodes.schemaTitle",
+};
+
+export const OPENAPI_SCHEMA = {
+  NO_SCHEMA: "theme.openapi.schema.noSchema",
+};
+
+export const OPENAPI_SCHEMA_ITEM = {
+  REQUIRED: "theme.openapi.schemaItem.required",
+  DEPRECATED: "theme.openapi.schemaItem.deprecated",
+  NULLABLE: "theme.openapi.schemaItem.nullable",
+  DEFAULT_VALUE: "theme.openapi.schemaItem.defaultValue",
+  EXAMPLE: "theme.openapi.schemaItem.example",
+  EXAMPLES: "theme.openapi.schemaItem.examples",
+  DESCRIPTION: "theme.openapi.schemaItem.description",
+  CONSTANT_VALUE: "theme.openapi.schemaItem.constantValue",
+  ENUM_VALUE: "theme.openapi.schemaItem.enumValue",
+  ENUM_DESCRIPTION: "theme.openapi.schemaItem.enumDescription",
+  POSSIBLE_VALUES: "theme.openapi.schemaItem.possibleValues",
+  ONE_OF: "theme.openapi.schemaItem.oneOf",
+  ANY_OF: "theme.openapi.schemaItem.anyOf",
+};
+
+export const OPENAPI_PARAMS_DETAILS = {
+  PARAMETERS_TITLE: "theme.openapi.paramsDetails.parametersTitle",
+};
+
+export const OPENAPI_SECURITY_SCHEMES = {
+  NAME: "theme.openapi.securitySchemes.name",
+  TYPE: "theme.openapi.securitySchemes.type",
+  SCOPES: "theme.openapi.securitySchemes.scopes",
+  IN: "theme.openapi.securitySchemes.in",
+  FLOWS: "theme.openapi.securitySchemes.flows",
+  DESCRIPTION: "theme.openapi.securitySchemes.description",
+  SCHEME: "theme.openapi.securitySchemes.scheme",
+  BEARER_FORMAT: "theme.openapi.securitySchemes.bearerFormat",
+  OPEN_ID_CONNECT_URL: "theme.openapi.securitySchemes.openIdConnectUrl",
+};