docusaurus-theme-openapi-docs 4.3.7 → 4.5.0

package/src/theme/ApiExplorer/FormFileUpload/_FormFileUpload.scss

@@ -13,7 +13,8 @@
 
   &:hover {
     border: 2px dashed var(--ifm-color-primary);
-    background: linear-gradient(
+    background:
+      linear-gradient(
         var(--openapi-dropzone-hover-shim),
         var(--openapi-dropzone-hover-shim)
       ),
@@ -38,7 +39,8 @@
   font-size: var(--ifm-code-font-size);
   border: 2px dashed var(--ifm-color-primary);
 
-  background: linear-gradient(
+  background:
+    linear-gradient(
       var(--openapi-dropzone-hover-shim),
       var(--openapi-dropzone-hover-shim)
     ),

package/src/theme/ApiExplorer/ParamOptions/_ParamOptions.scss

@@ -45,8 +45,8 @@
   line-height: 1.5;
 
   transition-property: color, background, border-color, box-shadow;
-  transition-duration: 100ms, 100ms, 100ms,
-    var(--ifm-button-transition-duration);
+  transition-duration:
+    100ms, 100ms, 100ms, var(--ifm-button-transition-duration);
   transition-timing-function: cubic-bezier(0.08, 0.52, 0.52, 1);
 
   -webkit-user-select: none;
@@ -85,8 +85,8 @@
   padding: 0.5rem 1rem;
   font-size: 12px;
   transition-property: color, background, border-color, box-shadow;
-  transition-duration: 100ms, 100ms, 100ms,
-    var(--ifm-button-transition-duration);
+  transition-duration:
+    100ms, 100ms, 100ms, var(--ifm-button-transition-duration);
   transition-timing-function: cubic-bezier(0.08, 0.52, 0.52, 1);
   user-select: none;
   white-space: nowrap;

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

@@ -26,7 +26,7 @@ import Server from "@theme/ApiExplorer/Server";
 import { useTypedDispatch, useTypedSelector } from "@theme/ApiItem/hooks";
 import { ParameterObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
 import { ApiItem } from "docusaurus-plugin-openapi-docs/src/types";
-import sdk from "postman-collection";
+import * as sdk from "postman-collection";
 import { FormProvider, useForm } from "react-hook-form";
 
 import makeRequest from "./makeRequest";
@@ -95,15 +95,38 @@ function Request({ item }: { item: ApiItem }) {
 
   const methods = useForm({ shouldFocusError: false });
 
+  const handleEventStream = async (res) => {
+    res.headers && dispatch(setHeaders(Object.fromEntries(res.headers)));
+    dispatch(setCode(res.status));
+
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let result = "";
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      result += decoder.decode(value, { stream: true });
+      dispatch(setResponse(result));
+    }
+  };
+
+  const handleResponse = async (res) => {
+    dispatch(setResponse(await res.text()));
+    dispatch(setCode(res.status));
+    res.headers && dispatch(setHeaders(Object.fromEntries(res.headers)));
+  };
+
   const onSubmit = async (data) => {
     dispatch(setResponse("Fetching..."));
     try {
       await delay(1200);
       const res = await makeRequest(postmanRequest, proxy, body);
-      dispatch(setResponse(await res.text()));
-      dispatch(setCode(res.status));
-      res.headers && dispatch(setHeaders(Object.fromEntries(res.headers)));
-    } catch (e: any) {
+      if (res.headers.get("content-type")?.includes("text/event-stream")) {
+        await handleEventStream(res);
+      } else {
+        await handleResponse(res);
+      }
+    } catch (e) {
       console.log(e);
       dispatch(setResponse("Connection failed"));
       dispatch(clearCode());

package/src/theme/ApiExplorer/Request/makeRequest.ts

@@ -6,7 +6,7 @@
  * ========================================================================== */
 
 import { Body } from "@theme/ApiExplorer/Body/slice";
-import sdk from "postman-collection";
+import * as sdk from "postman-collection";
 
 function fetchWithtimeout(
   url: string,
@@ -156,8 +156,9 @@ async function makeRequest(
         myHeaders.delete("Content-Type");
 
         myBody = new FormData();
-        if (Array.isArray(request.body.formdata.members)) {
-          for (const data of request.body.formdata.members) {
+        const members = (request.body as any)?.formdata?.members;
+        if (Array.isArray(members)) {
+          for (const data of members) {
             if (data.key && data.value.content) {
               myBody.append(data.key, data.value.content);
             }

package/src/theme/ApiExplorer/buildPostmanRequest.ts

@@ -12,7 +12,7 @@ import {
   ServerObject,
 } from "docusaurus-plugin-openapi-docs/src/openapi/types";
 import cloneDeep from "lodash/cloneDeep";
-import sdk from "postman-collection";
+import * as sdk from "postman-collection";
 
 type Param = {
   value?: string | string[];
@@ -73,7 +73,7 @@ function setQueryParams(postman: sdk.Request, queryParams: Param[]) {
             ([key, val]) =>
               new sdk.QueryParam({
                 key: `${param.name}[${key}]`,
-                value: val,
+                value: String(val),
               })
           );
         } else if (param.explode) {
@@ -81,7 +81,7 @@ function setQueryParams(postman: sdk.Request, queryParams: Param[]) {
             ([key, val]) =>
               new sdk.QueryParam({
                 key: key,
-                value: val,
+                value: String(val),
               })
           );
         } else {
@@ -181,7 +181,10 @@ function setPathParams(postman: sdk.Request, pathParams: Param[]) {
     });
   });
 
-  postman.url.variables.assimilate(source, false);
+  postman.url.variables.assimilate(
+    source.filter((v): v is sdk.Variable => v !== undefined),
+    false
+  );
 }
 
 function buildCookie(cookieParams: Param[]) {
@@ -207,7 +210,9 @@ function buildCookie(cookieParams: Param[]) {
                 ([key, val]) =>
                   new sdk.Cookie({
                     key: key,
-                    value: val,
+                    value: String(val),
+                    domain: "",
+                    path: "",
                   })
               );
             } else {
@@ -217,6 +222,8 @@ function buildCookie(cookieParams: Param[]) {
                 value: Object.entries(jsonResult)
                   .map(([key, val]) => `${key},${val}`)
                   .join(","),
+                domain: "",
+                path: "",
               });
             }
           }
@@ -224,7 +231,9 @@ function buildCookie(cookieParams: Param[]) {
           // Handle scalar values
           return new sdk.Cookie({
             key: param.name,
-            value: param.value,
+            value: String(param.value),
+            domain: "",
+            path: "",
           });
         }
       }
@@ -430,10 +439,9 @@ function buildPostmanRequest(
     clonedPostman.url.host = [url];
   }
 
-  setQueryParams(clonedPostman, queryParams);
-  setPathParams(clonedPostman, pathParams);
+  const enhancedQueryParams = [...queryParams];
+  const enhancedCookieParams = [...cookieParams];
 
-  const cookie = buildCookie(cookieParams);
   let otherHeaders = [];
 
   let selectedAuth: Scheme[] = [];
@@ -491,24 +499,46 @@ function buildPostmanRequest(
       continue;
     }
 
-    // API Key
+    // API Key in header
     if (a.type === "apiKey" && a.in === "header") {
       const { apiKey } = auth.data[a.key];
-      if (apiKey === undefined) {
-        otherHeaders.push({
-          key: a.name,
-          value: `<${a.name ?? a.type}>`,
-        });
-        continue;
-      }
       otherHeaders.push({
         key: a.name,
-        value: apiKey,
+        value: apiKey || `<${a.name ?? a.type}>`,
+      });
+      continue;
+    }
+
+    // API Key in query
+    if (a.type === "apiKey" && a.in === "query") {
+      const { apiKey } = auth.data[a.key];
+      enhancedQueryParams.push({
+        name: a.name,
+        in: "query",
+        value: apiKey || `<${a.name ?? a.type}>`,
+      });
+      continue;
+    }
+
+    // API Key in cookie
+    if (a.type === "apiKey" && a.in === "cookie") {
+      const { apiKey } = auth.data[a.key];
+      enhancedCookieParams.push({
+        name: a.name,
+        in: "cookie",
+        value: apiKey || `<${a.name ?? a.type}>`,
       });
       continue;
     }
   }
 
+  // Use the enhanced params that might include API keys
+  setQueryParams(clonedPostman, enhancedQueryParams);
+  setPathParams(clonedPostman, pathParams);
+
+  // Use enhanced cookie params that might include API keys
+  const cookie = buildCookie(enhancedCookieParams);
+
   setHeaders(
     clonedPostman,
     contentType,

package/src/theme/ApiExplorer/index.tsx

@@ -12,7 +12,7 @@ import Request from "@theme/ApiExplorer/Request";
 import Response from "@theme/ApiExplorer/Response";
 import SecuritySchemes from "@theme/ApiExplorer/SecuritySchemes";
 import { ApiItem } from "docusaurus-plugin-openapi-docs/src/types";
-import sdk from "postman-collection";
+import * as sdk from "postman-collection";
 
 function ApiExplorer({
   item,
@@ -21,7 +21,9 @@ function ApiExplorer({
   item: NonNullable<ApiItem>;
   infoPath: string;
 }) {
-  const postman = new sdk.Request(item.postman);
+  const postman = new sdk.Request(
+    item.postman ? (item.postman as any).toJSON() : {}
+  );
 
   return (
     <>

package/src/theme/CodeSamples/_CodeSamples.scss

@@ -0,0 +1,3 @@
+.openapi-code__code-samples-container {
+  margin-top: 2rem;
+}

package/src/theme/{ResponseSamples → CodeSamples}/index.tsx

@@ -11,21 +11,16 @@ import CodeBlock from "@theme/CodeBlock";
 import { Language } from "prism-react-renderer";
 
 export interface Props {
-  readonly responseExample: string;
+  readonly example: string;
   readonly language: Language;
 }
 
-function ResponseSamples({
-  responseExample,
-  language,
-}: Props): React.JSX.Element {
+function CodeSamples({ example, language }: Props): React.JSX.Element {
   return (
-    <div className="openapi-code__response-samples-container">
-      <CodeBlock language={language ? language : "json"}>
-        {responseExample}
-      </CodeBlock>
+    <div className="openapi-code__code-samples-container">
+      <CodeBlock language={language ? language : "json"}>{example}</CodeBlock>
     </div>
   );
 }
 
-export default ResponseSamples;
+export default CodeSamples;

package/src/theme/ParamsItem/index.tsx

@@ -16,10 +16,6 @@ import clsx from "clsx";
 import { getQualifierMessage, getSchemaName } from "../../markdown/schema";
 import { guard, toString } from "../../markdown/utils";
 
-interface Map<T> {
-  [key: string]: T;
-}
-
 export interface ExampleObject {
   summary?: string;
   description?: string;
@@ -32,7 +28,7 @@ export interface Props {
   param: {
     description: string;
     example: any;
-    examples: Map<ExampleObject>;
+    examples: Record<string, ExampleObject>;
     name: string;
     required: boolean;
     deprecated: boolean;
@@ -70,9 +66,14 @@ function ParamsItem({ param, ...rest }: Props) {
   let schema = param.schema;
   let defaultValue: string | undefined;
 
-  if (!schema || !schema?.type) {
+  if (!schema) {
     schema = { type: "any" };
   }
+
+  if (!schema.type) {
+    schema.type = "any";
+  }
+
   if (schema) {
     if (schema.items) {
       defaultValue = schema.items.default;

package/src/theme/ResponseExamples/index.tsx

@@ -7,8 +7,8 @@
 
 import React from "react";
 
+import CodeSamples from "@theme/CodeSamples";
 import Markdown from "@theme/Markdown";
-import ResponseSamples from "@theme/ResponseSamples";
 import TabItem from "@theme/TabItem";
 import { sampleResponseFromSchema } from "docusaurus-plugin-openapi-docs/lib/openapi/createResponseExample";
 import format from "xml-formatter";
@@ -78,10 +78,7 @@ export const ResponseExamples: React.FC<ResponseExamplesProps> = ({
               {exampleValue.summary}
             </Markdown>
           )}
-          <ResponseSamples
-            responseExample={responseExample}
-            language={language}
-          />
+          <CodeSamples example={responseExample} language={language} />
         </TabItem>
       );
     }
@@ -120,7 +117,7 @@ export const ResponseExample: React.FC<ResponseExampleProps> = ({
           {responseExample.summary}
         </Markdown>
       )}
-      <ResponseSamples responseExample={exampleContent} language={language} />
+      <CodeSamples example={exampleContent} language={language} />
     </TabItem>
   );
 };
@@ -167,7 +164,7 @@ export const ExampleFromSchema: React.FC<ExampleFromSchemaProps> = ({
       return (
         // @ts-ignore
         <TabItem label="Example (auto)" value="Example (auto)">
-          <ResponseSamples responseExample={xmlExample} language="xml" />
+          <CodeSamples example={xmlExample} language="xml" />
         </TabItem>
       );
     }
@@ -180,8 +177,8 @@ export const ExampleFromSchema: React.FC<ExampleFromSchemaProps> = ({
     return (
       // @ts-ignore
       <TabItem label="Example (auto)" value="Example (auto)">
-        <ResponseSamples
-          responseExample={JSON.stringify(responseExample, null, 2)}
+        <CodeSamples
+          example={JSON.stringify(responseExample, null, 2)}
           language="json"
         />
       </TabItem>

package/src/theme/Schema/index.tsx

@@ -21,7 +21,10 @@ import {
   getQualifierMessage,
   getSchemaName,
 } from "docusaurus-plugin-openapi-docs/lib/markdown/schema";
-import { SchemaObject } from "docusaurus-plugin-openapi-docs/lib/openapi/types";
+import {
+  SchemaObject,
+  SchemaType,
+} from "docusaurus-plugin-openapi-docs/lib/openapi/types";
 import isEmpty from "lodash/isEmpty";
 
 // eslint-disable-next-line import/no-extraneous-dependencies
@@ -113,7 +116,7 @@ const AnyOneOf: React.FC<SchemaProps> = ({ schema, schemaType }) => {
       </span>
       <SchemaTabs>
         {schema[type]?.map((anyOneSchema: any, index: number) => {
-          const label = anyOneSchema.title || `MOD${index + 1}`;
+          const label = anyOneSchema.title || anyOneSchema.type;
           return (
             // @ts-ignore
             <TabItem
@@ -122,9 +125,7 @@ const AnyOneOf: React.FC<SchemaProps> = ({ schema, schemaType }) => {
               value={`${index}-item-properties`}
             >
               {/* Handle primitive types directly */}
-              {["string", "number", "integer", "boolean"].includes(
-                anyOneSchema.type
-              ) && (
+              {(isPrimitive(anyOneSchema) || anyOneSchema.const) && (
                 <SchemaItem
                   collapsible={false}
                   name={undefined}
@@ -352,7 +353,8 @@ const DiscriminatorNode: React.FC<DiscriminatorNodeProps> = ({
     }
 
     const subProperties = subSchema.properties || mergedSubSchema.properties;
-    if (subProperties[discriminator.propertyName]) {
+    // Add a safeguard check to avoid referencing subProperties if it's undefined
+    if (subProperties && subProperties[discriminator.propertyName]) {
       if (schema.properties) {
         schema.properties![discriminator.propertyName] = {
           ...schema.properties![discriminator.propertyName],
@@ -502,88 +504,42 @@ const Items: React.FC<{
   schema: any;
   schemaType: "request" | "response";
 }> = ({ schema, schemaType }) => {
-  // Handles case when schema.items has properties
-  if (schema.items?.properties) {
-    return (
-      <>
-        <OpeningArrayBracket />
-        <Properties schema={schema.items} schemaType={schemaType} />
-        <ClosingArrayBracket />
-      </>
-    );
+  // Process schema.items to handle allOf merging
+  let itemsSchema = schema.items;
+  if (schema.items?.allOf) {
+    itemsSchema = mergeAllOf(schema.items) as SchemaObject;
   }
 
-  // Handles case when schema.items has additionalProperties
-  if (schema.items?.additionalProperties) {
-    return (
-      <>
-        <OpeningArrayBracket />
-        <AdditionalProperties schema={schema.items} schemaType={schemaType} />
-        <ClosingArrayBracket />
-      </>
-    );
-  }
+  // Handle complex schemas with multiple schema types
+  const hasOneOfAnyOf = itemsSchema?.oneOf || itemsSchema?.anyOf;
+  const hasProperties = itemsSchema?.properties;
+  const hasAdditionalProperties = itemsSchema?.additionalProperties;
 
-  // Handles case when schema.items has oneOf or anyOf
-  if (schema.items?.oneOf || schema.items?.anyOf) {
+  if (hasOneOfAnyOf || hasProperties || hasAdditionalProperties) {
     return (
       <>
         <OpeningArrayBracket />
-        <AnyOneOf schema={schema.items} schemaType={schemaType} />
+        {hasOneOfAnyOf && (
+          <AnyOneOf schema={itemsSchema} schemaType={schemaType} />
+        )}
+        {hasProperties && (
+          <Properties schema={itemsSchema} schemaType={schemaType} />
+        )}
+        {hasAdditionalProperties && (
+          <AdditionalProperties schema={itemsSchema} schemaType={schemaType} />
+        )}
         <ClosingArrayBracket />
       </>
     );
   }
 
-  // Handles case when schema.items has allOf
-  if (schema.items?.allOf) {
-    const mergedSchemas = mergeAllOf(schema.items) as SchemaObject;
-
-    // Handles combo anyOf/oneOf + properties
-    if (
-      (mergedSchemas.oneOf || mergedSchemas.anyOf) &&
-      mergedSchemas.properties
-    ) {
-      return (
-        <>
-          <OpeningArrayBracket />
-          <AnyOneOf schema={mergedSchemas} schemaType={schemaType} />
-          <Properties schema={mergedSchemas} schemaType={schemaType} />
-          <ClosingArrayBracket />
-        </>
-      );
-    }
-
-    // Handles only anyOf/oneOf
-    if (mergedSchemas.oneOf || mergedSchemas.anyOf) {
-      return (
-        <>
-          <OpeningArrayBracket />
-          <AnyOneOf schema={mergedSchemas} schemaType={schemaType} />
-          <ClosingArrayBracket />
-        </>
-      );
-    }
-
-    // Handles properties
-    if (mergedSchemas.properties) {
-      return (
-        <>
-          <OpeningArrayBracket />
-          <Properties schema={mergedSchemas} schemaType={schemaType} />
-          <ClosingArrayBracket />
-        </>
-      );
-    }
-  }
-
   // Handles basic types (string, number, integer, boolean, object)
   if (
-    schema.items?.type === "string" ||
-    schema.items?.type === "number" ||
-    schema.items?.type === "integer" ||
-    schema.items?.type === "boolean" ||
-    schema.items?.type === "object"
+    itemsSchema?.type === "string" ||
+    itemsSchema?.type === "number" ||
+    itemsSchema?.type === "integer" ||
+    itemsSchema?.type === "boolean" ||
+    itemsSchema?.type === "object"
   ) {
     return (
       <div style={{ marginLeft: ".5rem" }}>
@@ -591,9 +547,9 @@ const Items: React.FC<{
         <SchemaItem
           collapsible={false}
           name="" // No name for array items
-          schemaName={getSchemaName(schema.items)}
-          qualifierMessage={getQualifierMessage(schema.items)}
-          schema={schema.items}
+          schemaName={getSchemaName(itemsSchema)}
+          qualifierMessage={getQualifierMessage(itemsSchema)}
+          schema={itemsSchema}
           discriminator={false}
           children={null}
         />
@@ -606,7 +562,7 @@ const Items: React.FC<{
   return (
     <>
       <OpeningArrayBracket />
-      {Object.entries(schema.items || {}).map(([key, val]: [string, any]) => (
+      {Object.entries(itemsSchema || {}).map(([key, val]: [string, any]) => (
         <SchemaEdge
           key={key}
           name={key}
@@ -840,6 +796,25 @@ const SchemaEdge: React.FC<SchemaEdgeProps> = ({
   );
 };
 
+function renderChildren(
+  schema: SchemaObject,
+  schemaType: "request" | "response"
+) {
+  return (
+    <>
+      {schema.oneOf && <AnyOneOf schema={schema} schemaType={schemaType} />}
+      {schema.anyOf && <AnyOneOf schema={schema} schemaType={schemaType} />}
+      {schema.properties && (
+        <Properties schema={schema} schemaType={schemaType} />
+      )}
+      {schema.additionalProperties && (
+        <AdditionalProperties schema={schema} schemaType={schemaType} />
+      )}
+      {schema.items && <Items schema={schema} schemaType={schemaType} />}
+    </>
+  );
+}
+
 const SchemaNode: React.FC<SchemaProps> = ({ schema, schemaType }) => {
   if (
     (schemaType === "request" && schema.readOnly) ||
@@ -888,10 +863,6 @@ const SchemaNode: React.FC<SchemaProps> = ({ schema, schemaType }) => {
     );
   }
 
-  if (schema.oneOf || schema.anyOf) {
-    return <AnyOneOf schema={schema} schemaType={schemaType} />;
-  }
-
   // Handle primitives
   if (
     schema.type &&
@@ -917,19 +888,21 @@ const SchemaNode: React.FC<SchemaProps> = ({ schema, schemaType }) => {
     );
   }
 
-  return (
-    <div>
-      {schema.oneOf && <AnyOneOf schema={schema} schemaType={schemaType} />}
-      {schema.anyOf && <AnyOneOf schema={schema} schemaType={schemaType} />}
-      {schema.properties && (
-        <Properties schema={schema} schemaType={schemaType} />
-      )}
-      {schema.additionalProperties && (
-        <AdditionalProperties schema={schema} schemaType={schemaType} />
-      )}
-      {schema.items && <Items schema={schema} schemaType={schemaType} />}
-    </div>
-  );
+  return renderChildren(schema, schemaType);
 };
 
 export default SchemaNode;
+
+type PrimitiveSchemaType = Exclude<SchemaType, "object" | "array">;
+
+const PRIMITIVE_TYPES: Record<PrimitiveSchemaType, true> = {
+  string: true,
+  number: true,
+  integer: true,
+  boolean: true,
+  null: true,
+} as const;
+
+const isPrimitive = (schema: SchemaObject) => {
+  return PRIMITIVE_TYPES[schema.type as PrimitiveSchemaType];
+};