docusaurus-theme-openapi-docs 4.7.1 → 5.0.0

package/src/theme/ApiExplorer/Response/index.tsx

@@ -9,13 +9,13 @@ import React from "react";
 
 import { useDoc } from "@docusaurus/plugin-content-docs/client";
 import { usePrismTheme } from "@docusaurus/theme-common";
-import { translate } from "@docusaurus/Translate";
+import Translate, { translate } from "@docusaurus/Translate";
 import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
 import ApiCodeBlock from "@theme/ApiExplorer/ApiCodeBlock";
 import { useTypedDispatch, useTypedSelector } from "@theme/ApiItem/hooks";
 import SchemaTabs from "@theme/SchemaTabs";
 import TabItem from "@theme/TabItem";
-import { OPENAPI_RESPONSE } from "@theme/translationIds";
+import { OPENAPI_REQUEST, OPENAPI_RESPONSE } from "@theme/translationIds";
 import clsx from "clsx";
 import type { ApiItem } from "docusaurus-plugin-openapi-docs/src/types";
 import type { ThemeConfig } from "docusaurus-theme-openapi-docs/src/types";
@@ -84,7 +84,8 @@ function Response({ item }: { item: ApiItem }) {
         <span className="openapi-explorer__response-title">
           {translate({ id: OPENAPI_RESPONSE.TITLE, message: "Response" })}
         </span>
-        <span
+        <button
+          type="button"
           className="openapi-explorer__response-clear-btn"
           onClick={() => {
             dispatch(clearResponse());
@@ -93,7 +94,7 @@ function Response({ item }: { item: ApiItem }) {
           }}
         >
           {translate({ id: OPENAPI_RESPONSE.CLEAR, message: "Clear" })}
-        </span>
+        </button>
       </div>
       <div
         style={{
@@ -126,11 +127,22 @@ function Response({ item }: { item: ApiItem }) {
               >
                 {prettyResponse || (
                   <p className="openapi-explorer__response-placeholder-message">
-                    {translate({
-                      id: OPENAPI_RESPONSE.PLACEHOLDER,
-                      message:
-                        "Click the <code>Send API Request</code> button above and see the response here!",
-                    })}
+                    <Translate
+                      id={OPENAPI_RESPONSE.PLACEHOLDER}
+                      values={{
+                        code: (
+                          <code>
+                            <Translate id={OPENAPI_REQUEST.SEND_BUTTON}>
+                              Send API Request
+                            </Translate>
+                          </code>
+                        ),
+                      }}
+                    >
+                      {
+                        "Click the {code} button above and see the response here!"
+                      }
+                    </Translate>
                   </p>
                 )}
               </ApiCodeBlock>
@@ -163,11 +175,20 @@ function Response({ item }: { item: ApiItem }) {
           </div>
         ) : (
           <p className="openapi-explorer__response-placeholder-message">
-            {translate({
-              id: OPENAPI_RESPONSE.PLACEHOLDER,
-              message:
-                "Click the <code>Send API Request</code> button above and see the response here!",
-            })}
+            <Translate
+              id={OPENAPI_RESPONSE.PLACEHOLDER}
+              values={{
+                code: (
+                  <code>
+                    <Translate id={OPENAPI_REQUEST.SEND_BUTTON}>
+                      Send API Request
+                    </Translate>
+                  </code>
+                ),
+              }}
+            >
+              {"Click the {code} button above and see the response here!"}
+            </Translate>
           </p>
         )}
       </div>

package/src/theme/ApiExplorer/Server/index.tsx

@@ -17,7 +17,11 @@ import { OPENAPI_SERVER } from "@theme/translationIds";
 
 import { setServer, setServerVariable } from "./slice";
 
-function Server() {
+interface ServerProps {
+  labelId?: string;
+}
+
+function Server({ labelId }: ServerProps) {
   const [isEditing, setIsEditing] = useState(false);
   const value = useTypedSelector((state: any) => state.server.value);
   const options = useTypedSelector((state: any) => state.server.options);
@@ -79,6 +83,7 @@ function Server() {
       >
         <FormItem>
           <FormSelect
+            ariaLabelledBy={labelId}
             options={options.map((s: any) => s.url)}
             onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
               dispatch(
@@ -99,8 +104,9 @@ function Server() {
           Object.keys(value.variables).map((key) => {
             if (value.variables?.[key].enum !== undefined) {
               return (
-                <FormItem label={key}>
+                <FormItem>
                   <FormSelect
+                    label={key}
                     options={value.variables[key].enum}
                     onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
                       dispatch(
@@ -115,8 +121,9 @@ function Server() {
               );
             }
             return (
-              <FormItem label={key}>
+              <FormItem>
                 <FormTextInput
+                  label={key}
                   placeholder={value.variables?.[key].default}
                   onChange={(e: React.ChangeEvent<HTMLInputElement>) => {
                     dispatch(

package/src/theme/ApiExplorer/buildPostmanRequest.ts

@@ -293,12 +293,36 @@ function tryDecodeJsonParam(value: string): any {
 }
 
 // TODO: this is all a bit hacky
-function setBody(clonedPostman: sdk.Request, body: Body) {
+function setBody(
+  clonedPostman: sdk.Request,
+  body: Body,
+  encoding?: Record<string, { contentType?: string }>
+) {
   if (clonedPostman.body === undefined) {
     return;
   }
 
   if (body.type === "empty") {
+    // When the original request has formdata and encoding is declared, keep the
+    // placeholder params so the code snippet reflects the selected encoding even
+    // before the user has uploaded a file.
+    if (
+      clonedPostman.body?.mode === "formdata" &&
+      encoding &&
+      Object.keys(encoding).length > 0
+    ) {
+      const members: any[] =
+        (clonedPostman.body.formdata as any)?.members ?? [];
+      members.forEach((param: any) => {
+        const partContentType = encoding[param.key]?.contentType
+          ?.split(",")[0]
+          .trim();
+        if (partContentType) {
+          param.contentType = partContentType;
+        }
+      });
+      return;
+    }
     clonedPostman.body = undefined;
     return;
   }
@@ -336,14 +360,35 @@ function setBody(clonedPostman: sdk.Request, body: Body) {
       Object.entries(body.content)
         .filter((entry): entry is [string, NonNullable<Content>] => !!entry[1])
         .forEach(([key, content]) => {
+          const partContentType = encoding?.[key]?.contentType
+            ?.split(",")[0]
+            .trim();
           if (content.type === "file") {
-            params.push(new sdk.FormParam({ key: key, ...content }));
+            params.push(
+              new sdk.FormParam({
+                key: key,
+                ...content,
+                ...(partContentType && { contentType: partContentType }),
+              })
+            );
           } else if (content.type === "file[]") {
             content.value.forEach((file) =>
-              params.push(new sdk.FormParam({ key, value: file }))
+              params.push(
+                new sdk.FormParam({
+                  key,
+                  value: file,
+                  ...(partContentType && { contentType: partContentType }),
+                })
+              )
             );
           } else {
-            params.push(new sdk.FormParam({ key: key, value: content.value }));
+            params.push(
+              new sdk.FormParam({
+                key: key,
+                value: content.value,
+                ...(partContentType && { contentType: partContentType }),
+              })
+            );
           }
         });
       params.forEach((param) => {
@@ -391,6 +436,7 @@ interface Options {
   accept: string;
   body: Body;
   auth: AuthState;
+  encoding?: Record<string, { contentType?: string }>;
 }
 
 function buildPostmanRequest(
@@ -405,6 +451,7 @@ function buildPostmanRequest(
     body,
     server,
     auth,
+    encoding,
   }: Options
 ) {
   const clonedPostman = cloneDeep(postman);
@@ -532,7 +579,7 @@ function buildPostmanRequest(
     otherHeaders
   );
 
-  setBody(clonedPostman, body);
+  setBody(clonedPostman, body, encoding);
 
   return clonedPostman;
 }

package/src/theme/ApiExplorer/index.tsx

@@ -41,6 +41,7 @@ function ApiExplorer({
           postman={postman}
           codeSamples={(item as any)["x-codeSamples"] ?? []}
           maskCredentials={mask_credentials}
+          requestBody={item.requestBody}
         />
       )}
       <Request item={item} />

package/src/theme/ApiItem/index.tsx

@@ -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/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()}