docusaurus-theme-openapi-docs 0.0.0-1160 → 0.0.0-1162

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-theme-openapi-docs",
   "description": "OpenAPI theme for Docusaurus.",
-  "version": "0.0.0-1160",
+  "version": "0.0.0-1162",
   "license": "MIT",
   "keywords": [
     "openapi",
@@ -38,7 +38,7 @@
     "@types/postman-collection": "^3.5.11",
     "@types/react-modal": "^3.16.3",
     "concurrently": "^9.2.0",
-    "docusaurus-plugin-openapi-docs": "0.0.0-1160",
+    "docusaurus-plugin-openapi-docs": "0.0.0-1162",
     "docusaurus-plugin-sass": "^0.2.6",
     "eslint-plugin-prettier": "^5.5.1"
   },
@@ -82,5 +82,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "9590f36ccddb212cb31943e14654c4a9a6884ec5"
+  "gitHead": "91084c914a86e2522437018b04dd0a811e463451"
 }

package/src/theme/ApiExplorer/Body/FormBodyItem/index.tsx

@@ -17,6 +17,7 @@ import type { SchemaObject } from "docusaurus-plugin-openapi-docs/src/openapi/ty
 
 import FileArrayFormBodyItem from "../FileArrayFormBodyItem";
 import { clearFormBodyKey, setFileFormBody, setStringFormBody } from "../slice";
+import { setFieldEncoding } from "../../EncodingSelection/slice";
 
 interface FormBodyItemProps {
   schemaObject: SchemaObject;
@@ -25,6 +26,7 @@ interface FormBodyItemProps {
   label?: string;
   required?: boolean;
   exampleValue?: SchemaObject["example"];
+  fieldEncoding?: string;
 }
 
 export default function FormBodyItem({
@@ -34,8 +36,37 @@ export default function FormBodyItem({
   label,
   required,
   exampleValue,
+  fieldEncoding,
 }: FormBodyItemProps): React.JSX.Element {
   const dispatch = useTypedDispatch();
+
+  // Parse comma-separated encoding contentType into selectable options
+  const encodingOptions = fieldEncoding
+    ? fieldEncoding
+        .split(",")
+        .map((t) => t.trim())
+        .filter(Boolean)
+    : [];
+  const hasMultipleEncodings = encodingOptions.length > 1;
+
+  // Initialize with the first declared content type
+  const [selectedEncoding, setSelectedEncoding] = useState<string>(
+    encodingOptions[0] ?? ""
+  );
+
+  // Seed Redux with the first declared encoding on mount so the code snippet
+  // reflects a content type immediately, even before the user interacts.
+  // The empty dep array is intentional: `fieldEncoding` comes from a static
+  // spec value that never changes for the lifetime of this component instance,
+  // and re-seeding on every render would fight user selections.
+  useEffect(() => {
+    if (encodingOptions[0]) {
+      dispatch(
+        setFieldEncoding({ field: id, contentType: encodingOptions[0] })
+      );
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
   const [value, setValue] = useState(() => {
     let initialValue = exampleValue ?? "";
 
@@ -71,6 +102,20 @@ export default function FormBodyItem({
     return (
       <>
         {label && <FormLabel label={label} required={required} />}
+        {hasMultipleEncodings && (
+          <div style={{ marginTop: "0.5rem" }}>
+            <FormSelect
+              label="Content-Type"
+              options={encodingOptions}
+              value={selectedEncoding}
+              onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
+                const ct = e.target.value;
+                setSelectedEncoding(ct);
+                dispatch(setFieldEncoding({ field: id, contentType: ct }));
+              }}
+            />
+          </div>
+        )}
         <FormFileUpload
           placeholder={schemaObject.description || id}
           onChange={(file: any) => {
@@ -95,16 +140,16 @@ export default function FormBodyItem({
 
   if (schemaObject.type === "object") {
     return (
-    <>
-      {label && <FormLabel label={label} required={required} />}
-      <LiveApp
-        action={(code: string) =>
-          dispatch(setStringFormBody({ key: id, value: code }))
-        }
-      >
-        {value}
-      </LiveApp>
-    </>
+      <>
+        {label && <FormLabel label={label} required={required} />}
+        <LiveApp
+          action={(code: string) =>
+            dispatch(setStringFormBody({ key: id, value: code }))
+          }
+        >
+          {value}
+        </LiveApp>
+      </>
     );
   }
 

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

@@ -93,6 +93,8 @@ function Body({
   const rawSchema = requestBodyMetadata?.content?.[contentType]?.schema;
   const example = requestBodyMetadata?.content?.[contentType]?.example;
   const examples = requestBodyMetadata?.content?.[contentType]?.examples;
+  const encoding: Record<string, { contentType?: string }> | undefined =
+    requestBodyMetadata?.content?.[contentType]?.encoding;
 
   // Resolve the schema based on user's anyOf/oneOf tab selections
   const schema = useMemo(() => {
@@ -339,6 +341,7 @@ function Body({
                       Array.isArray(schema.required) &&
                       schema.required.includes(key)
                     }
+                    fieldEncoding={encoding?.[key]?.contentType}
                   ></FormBodyItem>
                 </FormItem>
               );
@@ -361,6 +364,7 @@ function Body({
                           Array.isArray(schema.required) &&
                           schema.required.includes(schemaKey)
                         }
+                        fieldEncoding={encoding?.[schemaKey]?.contentType}
                       ></FormBodyItem>
                     </FormItem>
                   );
@@ -387,6 +391,7 @@ function Body({
                               Array.isArray(schema.required) &&
                               schema.required.includes(schemaKey)
                             }
+                            fieldEncoding={encoding?.[schemaKey]?.contentType}
                           ></FormBodyItem>
                         </FormItem>
                       );

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

@@ -11,6 +11,7 @@ import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
 import ApiCodeBlock from "@theme/ApiExplorer/ApiCodeBlock";
 import buildPostmanRequest from "@theme/ApiExplorer/buildPostmanRequest";
 import CodeTabs from "@theme/ApiExplorer/CodeTabs";
+import { useResolvedEncoding } from "@theme/ApiExplorer/EncodingSelection/useResolvedEncoding";
 import { useTypedSelector } from "@theme/ApiItem/hooks";
 import cloneDeep from "lodash/cloneDeep";
 import codegen from "postman-code-generators";
@@ -30,6 +31,7 @@ export interface Props {
   postman: sdk.Request;
   codeSamples: CodeSample[];
   maskCredentials?: boolean;
+  requestBody?: import("docusaurus-plugin-openapi-docs/src/openapi/types").RequestBodyObject;
 }
 
 function CodeTab({ children, hidden, className }: any): React.JSX.Element {
@@ -44,6 +46,7 @@ function CodeSnippets({
   postman,
   codeSamples,
   maskCredentials: propMaskCredentials,
+  requestBody,
 }: Props) {
   const { siteConfig } = useDocusaurusContext();
 
@@ -76,7 +79,9 @@ function CodeSnippets({
               const authOptions =
                 clonedAuth?.options?.[key] ??
                 clonedAuth?.options?.[comboAuthId];
-              placeholder = authOptions?.find((opt: any) => opt.key === key)?.name;
+              placeholder = authOptions?.find(
+                (opt: any) => opt.key === key
+              )?.name;
               obj[key] = cleanCredentials(obj[key]);
             } else {
               obj[key] = `<${placeholder ?? key}>`;
@@ -93,6 +98,8 @@ function CodeSnippets({
       })()
     : auth;
 
+  const encoding = useResolvedEncoding(requestBody);
+
   // Create a Postman request object using cleanedAuth or original auth
   const cleanedPostmanRequest = buildPostmanRequest(postman, {
     queryParams,
@@ -104,6 +111,7 @@ function CodeSnippets({
     body,
     server,
     auth: cleanedAuth,
+    encoding,
   });
 
   // User-defined languages array

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

@@ -12,6 +12,7 @@ import FormSelect from "@theme/ApiExplorer/FormSelect";
 import { useTypedDispatch, useTypedSelector } from "@theme/ApiItem/hooks";
 
 import { setContentType } from "./slice";
+import { clearEncodingSelection } from "@theme/ApiExplorer/EncodingSelection/slice";
 
 function ContentType() {
   const value = useTypedSelector((state: any) => state.contentType.value);
@@ -28,9 +29,10 @@ function ContentType() {
         label="Content-Type"
         value={value}
         options={options}
-        onChange={(e: React.ChangeEvent<HTMLSelectElement>) =>
-          dispatch(setContentType(e.target.value))
-        }
+        onChange={(e: React.ChangeEvent<HTMLSelectElement>) => {
+          dispatch(setContentType(e.target.value));
+          dispatch(clearEncodingSelection());
+        }}
       />
     </FormItem>
   );

package/src/theme/ApiExplorer/EncodingSelection/slice.ts

@@ -0,0 +1,31 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+import { createSlice, PayloadAction } from "@reduxjs/toolkit";
+
+// Maps form field name → user-selected content type
+export type State = Record<string, string>;
+
+const initialState: State = {};
+
+export const slice = createSlice({
+  name: "encodingSelection",
+  initialState,
+  reducers: {
+    setFieldEncoding: (
+      state,
+      action: PayloadAction<{ field: string; contentType: string }>
+    ) => {
+      state[action.payload.field] = action.payload.contentType;
+    },
+    clearEncodingSelection: () => initialState,
+  },
+});
+
+export const { setFieldEncoding, clearEncodingSelection } = slice.actions;
+
+export default slice.reducer;

package/src/theme/ApiExplorer/EncodingSelection/useResolvedEncoding.ts

@@ -0,0 +1,43 @@
+/* ============================================================================
+ * 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.
+ * ========================================================================== */
+
+import { useTypedSelector } from "@theme/ApiItem/hooks";
+import type { RequestBodyObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
+
+/**
+ * Merges the spec-declared `encoding` for the active content type with any
+ * per-field content-type selections the user has made in the UI.  User picks
+ * take precedence over the spec default.
+ *
+ * Returns `undefined` when no encoding is declared for the current content
+ * type so callers can skip the encoding path entirely.
+ */
+export function useResolvedEncoding(
+  requestBody: RequestBodyObject | undefined
+): Record<string, { contentType?: string }> | undefined {
+  const contentType = useTypedSelector((state: any) => state.contentType.value);
+  const encodingSelection = useTypedSelector(
+    (state: any) => state.encodingSelection
+  );
+
+  const specEncoding: Record<string, { contentType?: string }> =
+    requestBody?.content?.[contentType]?.encoding ?? {};
+
+  if (!Object.keys(specEncoding).length) {
+    return undefined;
+  }
+
+  return Object.fromEntries(
+    Object.entries(specEncoding).map(([field, enc]) => [
+      field,
+      {
+        ...enc,
+        contentType: encodingSelection[field] ?? enc.contentType,
+      },
+    ])
+  );
+}

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

@@ -25,6 +25,7 @@ import {
   clearHeaders,
 } from "@theme/ApiExplorer/Response/slice";
 import Server from "@theme/ApiExplorer/Server";
+import { useResolvedEncoding } from "@theme/ApiExplorer/EncodingSelection/useResolvedEncoding";
 import { useTypedDispatch, useTypedSelector } from "@theme/ApiItem/hooks";
 import { OPENAPI_REQUEST } from "@theme/translationIds";
 import type { ParameterObject } from "docusaurus-plugin-openapi-docs/src/openapi/types";
@@ -76,6 +77,8 @@ function Request({ item }: { item: ApiItem }) {
     ...headerParams,
   ];
 
+  const encoding = useResolvedEncoding(item.requestBody);
+
   const postmanRequest = buildPostmanRequest(postman, {
     queryParams,
     pathParams,
@@ -86,6 +89,7 @@ function Request({ item }: { item: ApiItem }) {
     body,
     server,
     auth,
+    encoding,
   });
 
   const delay = (ms: number) =>
@@ -175,7 +179,8 @@ function Request({ item }: { item: ApiItem }) {
         proxy,
         body,
         requestTimeout,
-        requestCredentials
+        requestCredentials,
+        encoding
       );
       if (res.headers.get("content-type")?.includes("text/event-stream")) {
         await handleEventStream(res);