Add support for multiple body content types / examples

.changeset/green-lizards-change.md

@@ -0,0 +1,6 @@
+---
+"@gitbook/react-openapi": patch
+"gitbook": patch
+---
+
+Support body examples

packages/gitbook/src/components/DocumentView/OpenAPI/style.css

@@ -392,7 +392,11 @@
 }
 
 .openapi-codesample-footer {
-    @apply flex w-full justify-end;
+    @apply flex gap-3 w-full justify-between flex-wrap;
+}
+
+.openapi-codesample-selectors {
+    @apply flex flex-row items-center gap-3 flex-wrap;
 }
 
 /* Path */

packages/react-openapi/src/OpenAPICodeSample.tsx

@@ -1,21 +1,64 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import {
+    OpenAPIMediaTypeExamplesBody,
+    OpenAPIMediaTypeExamplesSelector,
+} from './OpenAPICodeSampleInteractive';
 import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
 import { ScalarApiButton } from './ScalarApiButton';
 import { StaticSection } from './StaticSection';
-import { type CodeSampleInput, codeSampleGenerators } from './code-samples';
-import { generateMediaTypeExample, generateSchemaExample } from './generateSchemaExample';
+import { type CodeSampleGenerator, codeSampleGenerators } from './code-samples';
+import { generateMediaTypeExamples, generateSchemaExample } from './generateSchemaExample';
 import { stringifyOpenAPI } from './stringifyOpenAPI';
 import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
 import { getDefaultServerURL } from './util/server';
 import { checkIsReference, createStateKey } from './utils';
 
+const CUSTOM_CODE_SAMPLES_KEYS = ['x-custom-examples', 'x-code-samples', 'x-codeSamples'] as const;
+
 /**
  * Display code samples to execute the operation.
  * It supports the Redocly custom syntax as well (https://redocly.com/docs/api-reference-docs/specification-extensions/x-code-samples/)
  */
 export function OpenAPICodeSample(props: {
     data: OpenAPIOperationData;
     context: OpenAPIContextProps;
+}) {
+    const { data } = props;
+
+    // If code samples are disabled at operation level, we don't display the code samples.
+    if (data.operation['x-codeSamples'] === false) {
+        return null;
+    }
+
+    const customCodeSamples = getCustomCodeSamples(props);
+
+    // If code samples are disabled at the top-level and not custom code samples are defined,
+    // we don't display the code samples.
+    if (data['x-codeSamples'] === false && !customCodeSamples) {
+        return null;
+    }
+
+    const samples = customCodeSamples ?? generateCodeSamples(props);
+
+    if (samples.length === 0) {
+        return null;
+    }
+
+    return (
+        <OpenAPITabs stateKey={createStateKey('codesample')} items={samples}>
+            <StaticSection header={<OpenAPITabsList />} className="openapi-codesample">
+                <OpenAPITabsPanels />
+            </StaticSection>
+        </OpenAPITabs>
+    );
+}
+
+/**
+ * Generate code samples for the operation.
+ */
+function generateCodeSamples(props: {
+    data: OpenAPIOperationData;
+    context: OpenAPIContextProps;
 }) {
     const { data, context } = props;
 
@@ -51,97 +94,102 @@ export function OpenAPICodeSample(props: {
     const requestBody = !checkIsReference(data.operation.requestBody)
         ? data.operation.requestBody
         : undefined;
-    const requestBodyContentEntries = requestBody?.content
-        ? Object.entries(requestBody.content)
-        : undefined;
-    const requestBodyContent = requestBodyContentEntries?.[0];
-
-    const input: CodeSampleInput = {
-        url:
-            getDefaultServerURL(data.servers) +
-            data.path +
-            (searchParams.size ? `?${searchParams.toString()}` : ''),
-        method: data.method,
-        body: requestBodyContent ? generateMediaTypeExample(requestBodyContent[1]) : undefined,
-        headers: {
-            ...getSecurityHeaders(data.securities),
-            ...headersObject,
-            ...(requestBodyContent
-                ? {
-                      'Content-Type': requestBodyContent[0],
-                  }
-                : undefined),
-        },
+
+    const url =
+        getDefaultServerURL(data.servers) +
+        data.path +
+        (searchParams.size ? `?${searchParams.toString()}` : '');
+
+    const genericHeaders = {
+        ...getSecurityHeaders(data.securities),
+        ...headersObject,
     };
 
-    const autoCodeSamples = codeSampleGenerators.map((generator) => ({
-        key: `default-${generator.id}`,
-        label: generator.label,
-        body: context.renderCodeBlock({
-            code: generator.generate(input),
-            syntax: generator.syntax,
-        }),
-        footer: <OpenAPICodeSampleFooter data={data} context={context} />,
-    }));
-
-    // Use custom samples if defined
-    let customCodeSamples: null | Array<{
-        key: string;
-        label: string;
-        body: React.ReactNode;
-    }> = null;
-    (['x-custom-examples', 'x-code-samples', 'x-codeSamples'] as const).forEach((key) => {
-        const customSamples = data.operation[key];
-        if (customSamples && Array.isArray(customSamples)) {
-            customCodeSamples = customSamples
-                .filter((sample) => {
-                    return (
-                        typeof sample.label === 'string' &&
-                        typeof sample.source === 'string' &&
-                        typeof sample.lang === 'string'
-                    );
-                })
-                .map((sample, index) => ({
-                    key: `redocly-${sample.lang}-${index}`,
-                    label: sample.label,
-                    body: context.renderCodeBlock({
-                        code: sample.source,
-                        syntax: sample.lang,
+    const mediaTypeRendererFactories = Object.entries(requestBody?.content ?? {}).map(
+        ([mediaType, mediaTypeObject]) => {
+            return (generator: CodeSampleGenerator) => {
+                const mediaTypeHeaders = {
+                    ...genericHeaders,
+                    'Content-Type': mediaType,
+                };
+                return {
+                    mediaType,
+                    element: context.renderCodeBlock({
+                        code: generator.generate({
+                            url,
+                            method: data.method,
+                            body: undefined,
+                            headers: mediaTypeHeaders,
+                        }),
+                        syntax: generator.syntax,
                     }),
-                    footer: <OpenAPICodeSampleFooter data={data} context={context} />,
-                }));
+                    examples: generateMediaTypeExamples(mediaTypeObject).map((example) => ({
+                        example,
+                        element: context.renderCodeBlock({
+                            code: generator.generate({
+                                url,
+                                method: data.method,
+                                body: example.value,
+                                headers: mediaTypeHeaders,
+                            }),
+                            syntax: generator.syntax,
+                        }),
+                    })),
+                } satisfies MediaTypeRenderer;
+            };
         }
-    });
-
-    // Code samples can be disabled at the top-level or at the operation level
-    // If code samples are defined at the operation level, it will override the top-level setting
-    const codeSamplesDisabled =
-        data['x-codeSamples'] === false || data.operation['x-codeSamples'] === false;
-    const samples = customCodeSamples ?? (!codeSamplesDisabled ? autoCodeSamples : []);
+    );
 
-    if (samples.length === 0) {
-        return null;
-    }
+    return codeSampleGenerators.map((generator) => {
+        if (mediaTypeRendererFactories.length > 0) {
+            const renderers = mediaTypeRendererFactories.map((generate) => generate(generator));
+            return {
+                key: `default-${generator.id}`,
+                label: generator.label,
+                body: <OpenAPIMediaTypeExamplesBody data={data} renderers={renderers} />,
+                footer: (
+                    <OpenAPICodeSampleFooter renderers={renderers} data={data} context={context} />
+                ),
+            };
+        }
+        return {
+            key: `default-${generator.id}`,
+            label: generator.label,
+            body: context.renderCodeBlock({
+                code: generator.generate({
+                    url,
+                    method: data.method,
+                    body: undefined,
+                    headers: genericHeaders,
+                }),
+                syntax: generator.syntax,
+            }),
+            footer: <OpenAPICodeSampleFooter data={data} renderers={[]} context={context} />,
+        };
+    });
+}
 
-    return (
-        <OpenAPITabs stateKey={createStateKey('codesample')} items={samples}>
-            <StaticSection header={<OpenAPITabsList />} className="openapi-codesample">
-                <OpenAPITabsPanels />
-            </StaticSection>
-        </OpenAPITabs>
-    );
+export interface MediaTypeRenderer {
+    mediaType: string;
+    element: React.ReactNode;
+    examples: Array<{
+        example: OpenAPIV3.ExampleObject;
+        element: React.ReactNode;
+    }>;
 }
 
 function OpenAPICodeSampleFooter(props: {
     data: OpenAPIOperationData;
+    renderers: MediaTypeRenderer[];
     context: OpenAPIContextProps;
 }) {
-    const { data, context } = props;
+    const { data, context, renderers } = props;
     const { method, path } = data;
     const { specUrl } = context;
     const hideTryItPanel = data['x-hideTryItPanel'] || data.operation['x-hideTryItPanel'];
+    const hasMediaTypes = renderers.length > 0;
 
-    if (hideTryItPanel) {
+    if (hideTryItPanel && !hasMediaTypes) {
         return null;
     }
 
@@ -151,11 +199,59 @@ function OpenAPICodeSampleFooter(props: {
 
     return (
         <div className="openapi-codesample-footer">
-            <ScalarApiButton method={method} path={path} specUrl={specUrl} />
+            {hasMediaTypes ? (
+                <OpenAPIMediaTypeExamplesSelector data={data} renderers={renderers} />
+            ) : (
+                <span />
+            )}
+            {!hideTryItPanel && <ScalarApiButton method={method} path={path} specUrl={specUrl} />}
         </div>
     );
 }
 
+/**
+ * Get custom code samples for the operation.
+ */
+function getCustomCodeSamples(props: {
+    data: OpenAPIOperationData;
+    context: OpenAPIContextProps;
+}) {
+    const { data, context } = props;
+
+    let customCodeSamples: null | Array<{
+        key: string;
+        label: string;
+        body: React.ReactNode;
+    }> = null;
+
+    CUSTOM_CODE_SAMPLES_KEYS.forEach((key) => {
+        const customSamples = data.operation[key];
+        if (customSamples && Array.isArray(customSamples)) {
+            customCodeSamples = customSamples
+                .filter((sample) => {
+                    return (
+                        typeof sample.label === 'string' &&
+                        typeof sample.source === 'string' &&
+                        typeof sample.lang === 'string'
+                    );
+                })
+                .map((sample, index) => ({
+                    key: `custom-sample-${sample.lang}-${index}`,
+                    label: sample.label,
+                    body: context.renderCodeBlock({
+                        code: sample.source,
+                        syntax: sample.lang,
+                    }),
+                    footer: (
+                        <OpenAPICodeSampleFooter renderers={[]} data={data} context={context} />
+                    ),
+                }));
+        }
+    });
+
+    return customCodeSamples;
+}
+
 function getSecurityHeaders(securities: OpenAPIOperationData['securities']): {
     [key: string]: string;
 } {