docusaurus-theme-openapi-docs 4.7.0 → 5.0.0

package/src/theme/ApiItem/index.tsx

@@ -22,7 +22,7 @@ import type { Props } from "@theme/DocItem";
 import DocItemMetadata from "@theme/DocItem/Metadata";
 import SkeletonLoader from "@theme/SkeletonLoader";
 import clsx from "clsx";
-import {
+import type {
   ParameterObject,
   ServerObject,
 } from "docusaurus-plugin-openapi-docs/src/openapi/types";
@@ -122,7 +122,7 @@ export default function ApiItem(props: Props): JSX.Element {
       (param: { in: "path" | "query" | "header" | "cookie" }) => {
         const paramType = param.in;
         const paramsArray: ParameterObject[] = params[paramType];
-        paramsArray.push(param as ParameterObject);
+        paramsArray?.push(param as ParameterObject);
       }
     );
     const auth = createAuth({
@@ -159,6 +159,7 @@ export default function ApiItem(props: Props): JSX.Element {
         params,
         auth,
         schemaSelection: { selections: {} },
+        encodingSelection: {},
       },
       [persistenceMiddleware]
     );

package/src/theme/ApiItem/store.ts

@@ -10,6 +10,7 @@ import accept from "@theme/ApiExplorer/Accept/slice";
 import auth from "@theme/ApiExplorer/Authorization/slice";
 import body from "@theme/ApiExplorer/Body/slice";
 import contentType from "@theme/ApiExplorer/ContentType/slice";
+import encodingSelection from "@theme/ApiExplorer/EncodingSelection/slice";
 import params from "@theme/ApiExplorer/ParamOptions/slice";
 import response from "@theme/ApiExplorer/Response/slice";
 import schemaSelection from "@theme/ApiExplorer/SchemaSelection/slice";
@@ -18,6 +19,7 @@ import server from "@theme/ApiExplorer/Server/slice";
 const rootReducer = combineReducers({
   accept,
   contentType,
+  encodingSelection,
   response,
   server,
   body,

package/src/theme/ApiTabs/index.tsx

@@ -15,11 +15,12 @@ import React, {
 
 import {
   sanitizeTabsChildren,
+  type TabItemProps,
   TabProps,
+  TabsProvider,
   useScrollPositionBlocker,
-  useTabs,
+  useTabsContextValue,
 } from "@docusaurus/theme-common/internal";
-import { TabItemProps } from "@docusaurus/theme-common/lib/utils/tabsUtils";
 import { translate } from "@docusaurus/Translate";
 import useIsBrowser from "@docusaurus/useIsBrowser";
 import Heading from "@theme/Heading";
@@ -42,7 +43,7 @@ function TabList({
     message: "Responses",
   }),
   id = "responses",
-}: TabListProps & ReturnType<typeof useTabs>) {
+}: TabListProps & ReturnType<typeof useTabsContextValue>) {
   const tabRefs: (HTMLLIElement | null)[] = [];
   const { blockElementScrollPositionUntilNextRender } =
     useScrollPositionBlocker();
@@ -194,7 +195,8 @@ function TabContent({
   lazy,
   children,
   selectedValue,
-}: TabProps & ReturnType<typeof useTabs>): React.JSX.Element | null {
+}: TabProps &
+  ReturnType<typeof useTabsContextValue>): React.JSX.Element | null {
   const childTabs = (Array.isArray(children) ? children : [children]).filter(
     Boolean
   ) as ReactElement<TabItemProps>[];
@@ -208,24 +210,17 @@ function TabContent({
     }
     return cloneElement(selectedTabItem, { className: "margin-top--md" });
   }
-  return (
-    <div className="margin-top--md">
-      {childTabs.map((tabItem, i) =>
-        cloneElement(tabItem, {
-          key: i,
-          hidden: tabItem.props.value !== selectedValue,
-        })
-      )}
-    </div>
-  );
+  return <div className="margin-top--md">{childTabs}</div>;
 }
 function TabsComponent(props: TabListProps): React.JSX.Element {
-  const tabs = useTabs(props);
+  const tabs = useTabsContextValue(props);
   return (
-    <div className="openapi-tabs__container">
-      <TabList {...props} {...tabs} />
-      <TabContent {...props} {...tabs} />
-    </div>
+    <TabsProvider value={tabs}>
+      <div className="openapi-tabs__container">
+        <TabList {...props} {...tabs} />
+        <TabContent {...props} {...tabs} />
+      </div>
+    </TabsProvider>
   );
 }
 export default function ApiTabs(props: TabListProps): React.JSX.Element {

package/src/theme/DiscriminatorTabs/index.tsx

@@ -15,11 +15,12 @@ import React, {
 
 import {
   sanitizeTabsChildren,
+  type TabItemProps,
   TabProps,
+  TabsProvider,
   useScrollPositionBlocker,
-  useTabs,
+  useTabsContextValue,
 } from "@docusaurus/theme-common/internal";
-import { TabItemProps } from "@docusaurus/theme-common/lib/utils/tabsUtils";
 import useIsBrowser from "@docusaurus/useIsBrowser";
 import clsx from "clsx";
 import flatten from "lodash/flatten";
@@ -30,7 +31,7 @@ function TabList({
   selectedValue,
   selectValue,
   tabValues,
-}: TabProps & ReturnType<typeof useTabs>) {
+}: TabProps & ReturnType<typeof useTabsContextValue>) {
   const tabRefs: (HTMLLIElement | null)[] = [];
   const { blockElementScrollPositionUntilNextRender } =
     useScrollPositionBlocker();
@@ -172,7 +173,8 @@ function TabContent({
   lazy,
   children,
   selectedValue,
-}: TabProps & ReturnType<typeof useTabs>): React.JSX.Element | null {
+}: TabProps &
+  ReturnType<typeof useTabsContextValue>): React.JSX.Element | null {
   const childTabs = (Array.isArray(children) ? children : [children]).filter(
     Boolean
   ) as ReactElement<TabItemProps>[];
@@ -187,24 +189,17 @@ function TabContent({
     }
     return cloneElement(selectedTabItem, { className: "margin-top--md" });
   }
-  return (
-    <div className="margin-top--md">
-      {childTabs.map((tabItem, i) =>
-        cloneElement(tabItem, {
-          key: i,
-          hidden: tabItem.props.value !== selectedValue,
-        })
-      )}
-    </div>
-  );
+  return <div className="margin-top--md">{childTabs}</div>;
 }
 function TabsComponent(props: TabProps): React.JSX.Element {
-  const tabs = useTabs(props);
+  const tabs = useTabsContextValue(props);
   return (
-    <div className="openapi-tabs__container">
-      <TabList {...props} {...tabs} />
-      <TabContent {...props} {...tabs} />
-    </div>
+    <TabsProvider value={tabs}>
+      <div className="openapi-tabs__container">
+        <TabList {...props} {...tabs} />
+        <TabContent {...props} {...tabs} />
+      </div>
+    </TabsProvider>
   );
 }
 export default function DiscriminatorTabs(props: TabProps): React.JSX.Element {

package/src/theme/MimeTabs/index.tsx

@@ -15,11 +15,12 @@ import React, {
 
 import {
   sanitizeTabsChildren,
+  type TabItemProps,
   TabProps,
+  TabsProvider,
   useScrollPositionBlocker,
-  useTabs,
+  useTabsContextValue,
 } from "@docusaurus/theme-common/internal";
-import { TabItemProps } from "@docusaurus/theme-common/lib/utils/tabsUtils";
 import useIsBrowser from "@docusaurus/useIsBrowser";
 import { setAccept } from "@theme/ApiExplorer/Accept/slice";
 import { setContentType } from "@theme/ApiExplorer/ContentType/slice";
@@ -38,7 +39,9 @@ function TabList({
   selectValue,
   tabValues,
   schemaType,
-}: Props & TabProps & ReturnType<typeof useTabs>): React.JSX.Element {
+}: Props &
+  TabProps &
+  ReturnType<typeof useTabsContextValue>): React.JSX.Element {
   const tabRefs: (HTMLLIElement | null)[] = [];
   const { blockElementScrollPositionUntilNextRender } =
     useScrollPositionBlocker();
@@ -208,7 +211,7 @@ function TabContent({
   lazy,
   children,
   selectedValue,
-}: Props & TabProps & ReturnType<typeof useTabs>) {
+}: Props & TabProps & ReturnType<typeof useTabsContextValue>) {
   const childTabs = (Array.isArray(children) ? children : [children]).filter(
     Boolean
   ) as ReactElement<TabItemProps>[];
@@ -222,24 +225,17 @@ function TabContent({
     }
     return cloneElement(selectedTabItem, { className: "margin-top--md" });
   }
-  return (
-    <div className="margin-top--md">
-      {childTabs.map((tabItem, i) =>
-        cloneElement(tabItem, {
-          key: i,
-          hidden: tabItem.props.value !== selectedValue,
-        })
-      )}
-    </div>
-  );
+  return <div className="margin-top--md">{childTabs}</div>;
 }
 function TabsComponent(props: Props & TabProps): React.JSX.Element {
-  const tabs = useTabs(props);
+  const tabs = useTabsContextValue(props);
   return (
-    <div className="tabs-container">
-      <TabList {...props} {...tabs} />
-      <TabContent {...props} {...tabs} />
-    </div>
+    <TabsProvider value={tabs}>
+      <div className="tabs-container">
+        <TabList {...props} {...tabs} />
+        <TabContent {...props} {...tabs} />
+      </div>
+    </TabsProvider>
   );
 }
 export default function MimeTabs(props: Props & TabProps) {

package/src/theme/OperationTabs/index.tsx

@@ -15,11 +15,12 @@ import React, {
 
 import {
   sanitizeTabsChildren,
+  type TabItemProps,
   TabProps,
+  TabsProvider,
   useScrollPositionBlocker,
-  useTabs,
+  useTabsContextValue,
 } from "@docusaurus/theme-common/internal";
-import { TabItemProps } from "@docusaurus/theme-common/lib/utils/tabsUtils";
 import useIsBrowser from "@docusaurus/useIsBrowser";
 import clsx from "clsx";
 
@@ -29,7 +30,7 @@ function TabList({
   selectedValue,
   selectValue,
   tabValues,
-}: TabProps & ReturnType<typeof useTabs>) {
+}: TabProps & ReturnType<typeof useTabsContextValue>) {
   const tabRefs: (HTMLLIElement | null)[] = [];
   const { blockElementScrollPositionUntilNextRender } =
     useScrollPositionBlocker();
@@ -171,7 +172,8 @@ function TabContent({
   lazy,
   children,
   selectedValue,
-}: TabProps & ReturnType<typeof useTabs>): React.JSX.Element | null {
+}: TabProps &
+  ReturnType<typeof useTabsContextValue>): React.JSX.Element | null {
   const childTabs = (Array.isArray(children) ? children : [children]).filter(
     Boolean
   ) as ReactElement<TabItemProps>[];
@@ -185,24 +187,17 @@ function TabContent({
     }
     return cloneElement(selectedTabItem, { className: "margin-top--md" });
   }
-  return (
-    <div className="margin-top--md">
-      {childTabs.map((tabItem, i) =>
-        cloneElement(tabItem, {
-          key: i,
-          hidden: tabItem.props.value !== selectedValue,
-        })
-      )}
-    </div>
-  );
+  return <div className="margin-top--md">{childTabs}</div>;
 }
 function TabsComponent(props: TabProps): React.JSX.Element {
-  const tabs = useTabs(props);
+  const tabs = useTabsContextValue(props);
   return (
-    <div className="tabs-container">
-      <TabList {...props} {...tabs} />
-      <TabContent {...props} {...tabs} />
-    </div>
+    <TabsProvider value={tabs}>
+      <div className="tabs-container">
+        <TabList {...props} {...tabs} />
+        <TabContent {...props} {...tabs} />
+      </div>
+    </TabsProvider>
   );
 }
 export default function OperationTabs(props: TabProps): React.JSX.Element {

package/src/theme/ParamsDetails/index.tsx

@@ -7,13 +7,12 @@
 
 import React from "react";
 
-import { translate } from "@docusaurus/Translate";
-import { OPENAPI_PARAMS_DETAILS } from "@theme/translationIds";
-
 import BrowserOnly from "@docusaurus/BrowserOnly";
+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[];

package/src/theme/ParamsItem/index.tsx

@@ -102,10 +102,34 @@ function ParamsItem({ param, ...rest }: Props) {
     </span>
   ));
 
+  const constValue = schema?.const;
+
   const renderQualifier = guard(getQualifierMessage(schema), (qualifier) => (
     <Markdown>{qualifier}</Markdown>
   ));
 
+  function renderConstValue() {
+    if (constValue === undefined) {
+      return undefined;
+    }
+    const label = translate({
+      id: OPENAPI_SCHEMA_ITEM.CONSTANT_VALUE,
+      message: "Constant value:",
+    });
+    return (
+      <div>
+        <strong>{label} </strong>
+        <span>
+          <code>
+            {typeof constValue === "string"
+              ? constValue
+              : JSON.stringify(constValue)}
+          </code>
+        </span>
+      </div>
+    );
+  }
+
   const renderDescription = guard(description, (description) => (
     <Markdown>{description}</Markdown>
   ));
@@ -173,6 +197,7 @@ function ParamsItem({ param, ...rest }: Props) {
         {renderDeprecated}
       </span>
       {renderQualifier}
+      {renderConstValue()}
       {renderDescription}
       {renderEnumDescriptions}
       {renderDefaultValue()}

package/src/theme/RequestSchema/index.tsx

@@ -7,17 +7,22 @@
 
 import React from "react";
 
-import { translate } from "@docusaurus/Translate";
-import { OPENAPI_REQUEST, OPENAPI_SCHEMA_ITEM } from "@theme/translationIds";
-
 import BrowserOnly from "@docusaurus/BrowserOnly";
+import { translate } from "@docusaurus/Translate";
 import Details from "@theme/Details";
 import Markdown from "@theme/Markdown";
 import MimeTabs from "@theme/MimeTabs"; // Assume these components exist
+import {
+  ExampleFromSchema,
+  ResponseExample,
+  ResponseExamples,
+} from "@theme/ResponseExamples";
 import SchemaNode from "@theme/Schema";
+import SchemaTabs from "@theme/SchemaTabs";
 import SkeletonLoader from "@theme/SkeletonLoader";
 import TabItem from "@theme/TabItem";
-import { MediaTypeObject } from "docusaurus-plugin-openapi-docs/lib/openapi/types";
+import { OPENAPI_REQUEST, OPENAPI_SCHEMA_ITEM } from "@theme/translationIds";
+import type { MediaTypeObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
 
 interface Props {
   style?: React.CSSProperties;
@@ -47,7 +52,11 @@ const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
     return (
       <MimeTabs className="openapi-tabs__mime" schemaType="request" lazy>
         {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 &&
@@ -58,49 +67,73 @@ const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
           return (
             // @ts-ignore
             <TabItem key={mimeType} label={mimeType} value={mimeType}>
-              <div style={{ marginTop: "1rem" }}>
-                <Details
-                  className="openapi-markdown__details mime"
-                  data-collapsed={false}
-                  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">
+              <SchemaTabs className="openapi-tabs__schema">
+                {/* @ts-ignore */}
+                <TabItem key={title} label={title} value={title}>
+                  <div style={{ marginTop: "1rem" }}>
+                    <Details
+                      className="openapi-markdown__details mime"
+                      data-collapsed={false}
+                      open={true}
+                      style={style}
+                      summary={
+                        <>
+                          <summary>
+                            <h3 className="openapi-markdown__details-summary-header-body">
                               {translate({
-                                id: OPENAPI_SCHEMA_ITEM.REQUIRED,
-                                message: "required",
+                                id: OPENAPI_REQUEST.BODY_TITLE,
+                                message: title,
                               })}
-                            </span>
-                          )}
-                        </h3>
-                      </summary>
-                    </>
-                  }
-                >
-                  <div style={{ textAlign: "left", marginLeft: "1rem" }}>
-                    {body.description && (
-                      <div style={{ marginTop: "1rem", marginBottom: "1rem" }}>
-                        <Markdown>{body.description}</Markdown>
+                              {body.required === true && (
+                                <span className="openapi-schema__required">
+                                  {translate({
+                                    id: OPENAPI_SCHEMA_ITEM.REQUIRED,
+                                    message: "required",
+                                  })}
+                                </span>
+                              )}
+                            </h3>
+                          </summary>
+                        </>
+                      }
+                    >
+                      <div style={{ textAlign: "left", marginLeft: "1rem" }}>
+                        {body.description && (
+                          <div
+                            style={{ marginTop: "1rem", marginBottom: "1rem" }}
+                          >
+                            <Markdown>{body.description}</Markdown>
+                          </div>
+                        )}
                       </div>
-                    )}
+                      <ul style={{ marginLeft: "1rem" }}>
+                        <SchemaNode
+                          schema={firstBody}
+                          schemaType="request"
+                          schemaPath="requestBody"
+                        />
+                      </ul>
+                    </Details>
                   </div>
-                  <ul style={{ marginLeft: "1rem" }}>
-                    <SchemaNode
-                      schema={firstBody}
-                      schemaType="request"
-                      schemaPath="requestBody"
-                    />
-                  </ul>
-                </Details>
-              </div>
+                </TabItem>
+                {firstBody &&
+                  !requestExample &&
+                  !requestExamples &&
+                  ExampleFromSchema({
+                    schema: firstBody,
+                    mimeType: mimeType,
+                  })}
+                {requestExamples &&
+                  ResponseExamples({
+                    responseExamples: requestExamples,
+                    mimeType,
+                  })}
+                {requestExample &&
+                  ResponseExample({
+                    responseExample: requestExample,
+                    mimeType,
+                  })}
+              </SchemaTabs>
             </TabItem>
           );
         })}
@@ -109,8 +142,10 @@ const RequestSchemaComponent: React.FC<Props> = ({ 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;
@@ -120,50 +155,72 @@ const RequestSchemaComponent: React.FC<Props> = ({ title, body, style }) => {
     <MimeTabs className="openapi-tabs__mime" schemaType="request">
       {/* @ts-ignore */}
       <TabItem label={randomFirstKey} value={`${randomFirstKey}-schema`}>
-        <Details
-          className="openapi-markdown__details mime"
-          data-collapsed={false}
-          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">
+        <SchemaTabs className="openapi-tabs__schema">
+          {/* @ts-ignore */}
+          <TabItem key={title} label={title} value={title}>
+            <Details
+              className="openapi-markdown__details mime"
+              data-collapsed={false}
+              open={true}
+              style={style}
+              summary={
+                <>
+                  <summary>
+                    <h3 className="openapi-markdown__details-summary-header-body">
                       {translate({
-                        id: OPENAPI_SCHEMA_ITEM.REQUIRED,
-                        message: "required",
+                        id: OPENAPI_REQUEST.BODY_TITLE,
+                        message: title,
                       })}
-                    </strong>
-                  )}
-                </h3>
-              </summary>
-            </>
-          }
-        >
-          <div style={{ textAlign: "left", marginLeft: "1rem" }}>
-            {body.description && (
-              <div style={{ marginTop: "1rem", marginBottom: "1rem" }}>
-                <Markdown>{body.description}</Markdown>
+                      {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>
+                </>
+              }
+            >
+              <div style={{ textAlign: "left", marginLeft: "1rem" }}>
+                {body.description && (
+                  <div style={{ marginTop: "1rem", marginBottom: "1rem" }}>
+                    <Markdown>{body.description}</Markdown>
+                  </div>
+                )}
               </div>
-            )}
-          </div>
-          <ul style={{ marginLeft: "1rem" }}>
-            <SchemaNode
-              schema={firstBody}
-              schemaType="request"
-              schemaPath="requestBody"
-            />
-          </ul>
-        </Details>
+              <ul style={{ marginLeft: "1rem" }}>
+                <SchemaNode
+                  schema={firstBody}
+                  schemaType="request"
+                  schemaPath="requestBody"
+                />
+              </ul>
+            </Details>
+          </TabItem>
+          {firstBody &&
+            !requestExample &&
+            !requestExamples &&
+            ExampleFromSchema({
+              schema: firstBody,
+              mimeType: randomFirstKey,
+            })}
+          {requestExamples &&
+            ResponseExamples({
+              responseExamples: requestExamples,
+              mimeType: randomFirstKey,
+            })}
+          {requestExample &&
+            ResponseExample({
+              responseExample: requestExample,
+              mimeType: randomFirstKey,
+            })}
+        </SchemaTabs>
       </TabItem>
     </MimeTabs>
   );

package/src/theme/ResponseHeaders/index.tsx

@@ -9,7 +9,7 @@ import React from "react";
 
 import SchemaItem from "@theme/SchemaItem";
 
-import { getQualifierMessage, getSchemaName } from "../../markdown/schema";
+import { getSchemaName } from "../../markdown/schema";
 
 interface ResponseHeadersProps {
   description?: string;
@@ -35,7 +35,6 @@ export const ResponseHeaders: React.FC<{
             name={name}
             collapsible={false}
             schemaName={getSchemaName(schema)}
-            qualifierMessage={getQualifierMessage(schema)}
             schema={schema}
             discriminator={false}
             children={null}