@gitbook/react-openapi 1.1.4 → 1.1.6

package/dist/utils.d.ts

@@ -1,5 +1,5 @@
 import type { AnyObject, OpenAPIV3, OpenAPIV3_1 } from '@gitbook/openapi-parser';
-export declare function checkIsReference(input: unknown): input is OpenAPIV3.ReferenceObject | OpenAPIV3_1.ReferenceObject;
+export declare function checkIsReference(input: unknown): input is OpenAPIV3.ReferenceObject;
 export declare function createStateKey(key: string, scope?: string): string;
 /**
  * Resolve the description of an object.

package/dist/utils.js

@@ -26,16 +26,20 @@ function hasDescription(object) {
  * Resolve the description of an object.
  */
 export function resolveDescription(object) {
-    // If the object has items and has a description, we resolve the description from items
+    // Resolve description from the object first
+    if (hasDescription(object)) {
+        return 'x-gitbook-description-html' in object &&
+            typeof object['x-gitbook-description-html'] === 'string'
+            ? object['x-gitbook-description-html'].trim()
+            : typeof object.description === 'string'
+                ? object.description.trim()
+                : undefined;
+    }
+    // If the object has no description, try to resolve it from the items
     if ('items' in object && typeof object.items === 'object' && hasDescription(object.items)) {
         return resolveDescription(object.items);
     }
-    return 'x-gitbook-description-html' in object &&
-        typeof object['x-gitbook-description-html'] === 'string'
-        ? object['x-gitbook-description-html'].trim()
-        : typeof object.description === 'string'
-            ? object.description.trim()
-            : undefined;
+    return undefined;
 }
 /**
  * Extract descriptions from an object.

package/package.json

@@ -8,12 +8,12 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "1.1.4",
+    "version": "1.1.6",
     "sideEffects": false,
     "dependencies": {
         "@gitbook/openapi-parser": "workspace:*",
-        "@scalar/api-client-react": "^1.1.36",
-        "@scalar/oas-utils": "^0.2.110",
+        "@scalar/api-client-react": "^1.2.5",
+        "@scalar/oas-utils": "^0.2.120",
         "clsx": "^2.1.1",
         "flatted": "^3.2.9",
         "json-xml-parse": "^1.3.0",

package/src/OpenAPICodeSample.tsx

@@ -1,12 +1,20 @@
+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/)
@@ -14,6 +22,43 @@ import { checkIsReference, createStateKey } from './utils';
 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;
 
@@ -49,45 +94,139 @@ 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,
-        }),
-    }));
+    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,
+                    }),
+                    examples: generateMediaTypeExamples(mediaTypeObject, {
+                        mode: 'write',
+                    }).map((example) => ({
+                        example,
+                        element: context.renderCodeBlock({
+                            code: generator.generate({
+                                url,
+                                method: data.method,
+                                body: example.value,
+                                headers: mediaTypeHeaders,
+                            }),
+                            syntax: generator.syntax,
+                        }),
+                    })),
+                } satisfies MediaTypeRenderer;
+            };
+        }
+    );
+
+    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} />,
+        };
+    });
+}
+
+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, 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 && !hasMediaTypes) {
+        return null;
+    }
+
+    if (!validateHttpMethod(method)) {
+        return null;
+    }
+
+    return (
+        <div className="openapi-codesample-footer">
+            {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;
 
-    // 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) => {
+
+    CUSTOM_CODE_SAMPLES_KEYS.forEach((key) => {
         const customSamples = data.operation[key];
         if (customSamples && Array.isArray(customSamples)) {
             customCodeSamples = customSamples
@@ -99,33 +238,20 @@ export function OpenAPICodeSample(props: {
                     );
                 })
                 .map((sample, index) => ({
-                    key: `redocly-${sample.lang}-${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} />
+                    ),
                 }));
         }
     });
 
-    // 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 (
-        <OpenAPITabs stateKey={createStateKey('codesample')} items={samples}>
-            <StaticSection header={<OpenAPITabsList />} className="openapi-codesample">
-                <OpenAPITabsPanels />
-            </StaticSection>
-        </OpenAPITabs>
-    );
+    return customCodeSamples;
 }
 
 function getSecurityHeaders(securities: OpenAPIOperationData['securities']): {
@@ -169,3 +295,7 @@ function getSecurityHeaders(securities: OpenAPIOperationData['securities']): {
         }
     }
 }
+
+function validateHttpMethod(method: string): method is OpenAPIV3.HttpMethods {
+    return ['get', 'post', 'put', 'delete', 'patch', 'head', 'options', 'trace'].includes(method);
+}

package/src/OpenAPICodeSampleInteractive.tsx

@@ -0,0 +1,114 @@
+'use client';
+import clsx from 'clsx';
+import { useCallback } from 'react';
+import { useStore } from 'zustand';
+import type { MediaTypeRenderer } from './OpenAPICodeSample';
+import type { OpenAPIOperationData } from './types';
+import { getOrCreateTabStoreByKey } from './useSyncedTabsGlobalState';
+
+function useMediaTypeState(data: OpenAPIOperationData, defaultKey: string) {
+    const { method, path } = data;
+    const store = useStore(getOrCreateTabStoreByKey(`media-type-${method}-${path}`, defaultKey));
+    if (typeof store.tabKey !== 'string') {
+        throw new Error('Media type key is not a string');
+    }
+    return {
+        mediaType: store.tabKey,
+        setMediaType: useCallback((index: string) => store.setTabKey(index), [store.setTabKey]),
+    };
+}
+
+function useMediaTypeSampleIndexState(data: OpenAPIOperationData, mediaType: string) {
+    const { method, path } = data;
+    const store = useStore(
+        getOrCreateTabStoreByKey(`media-type-sample-${mediaType}-${method}-${path}`, 0)
+    );
+    if (typeof store.tabKey !== 'number') {
+        throw new Error('Example key is not a number');
+    }
+    return {
+        index: store.tabKey,
+        setIndex: useCallback((index: number) => store.setTabKey(index), [store.setTabKey]),
+    };
+}
+
+export function OpenAPIMediaTypeExamplesSelector(props: {
+    data: OpenAPIOperationData;
+    renderers: MediaTypeRenderer[];
+}) {
+    const { data, renderers } = props;
+    if (!renderers[0]) {
+        throw new Error('No renderers provided');
+    }
+    const state = useMediaTypeState(data, renderers[0].mediaType);
+    const selected = renderers.find((r) => r.mediaType === state.mediaType) || renderers[0];
+
+    return (
+        <div className="openapi-codesample-selectors">
+            <select
+                className={clsx('openapi-select')}
+                value={state.mediaType}
+                onChange={(e) => state.setMediaType(e.target.value)}
+            >
+                {renderers.map((renderer) => (
+                    <option key={renderer.mediaType} value={renderer.mediaType}>
+                        {renderer.mediaType}
+                    </option>
+                ))}
+            </select>
+            <ExamplesSelector data={data} renderer={selected} />
+        </div>
+    );
+}
+
+function ExamplesSelector(props: {
+    data: OpenAPIOperationData;
+    renderer: MediaTypeRenderer;
+}) {
+    const { data, renderer } = props;
+    const state = useMediaTypeSampleIndexState(data, renderer.mediaType);
+    if (renderer.examples.length < 2) {
+        return null;
+    }
+
+    return (
+        <select
+            className={clsx('openapi-select')}
+            value={String(state.index)}
+            onChange={(e) => state.setIndex(Number(e.target.value))}
+        >
+            {renderer.examples.map((example, index) => (
+                <option key={index} value={index}>
+                    {example.example.summary || `Example ${index + 1}`}
+                </option>
+            ))}
+        </select>
+    );
+}
+
+export function OpenAPIMediaTypeExamplesBody(props: {
+    data: OpenAPIOperationData;
+    renderers: MediaTypeRenderer[];
+}) {
+    const { renderers, data } = props;
+    if (!renderers[0]) {
+        throw new Error('No renderers provided');
+    }
+    const mediaTypeState = useMediaTypeState(data, renderers[0].mediaType);
+    const selected =
+        renderers.find((r) => r.mediaType === mediaTypeState.mediaType) ?? renderers[0];
+    if (selected.examples.length === 0) {
+        return selected.element;
+    }
+    return <ExamplesBody data={data} renderer={selected} />;
+}
+
+function ExamplesBody(props: { data: OpenAPIOperationData; renderer: MediaTypeRenderer }) {
+    const { data, renderer } = props;
+    const exampleState = useMediaTypeSampleIndexState(data, renderer.mediaType);
+    const example = renderer.examples[exampleState.index] ?? renderer.examples[0];
+    if (!example) {
+        throw new Error(`No example found for index ${exampleState.index}`);
+    }
+    return example.element;
+}

package/src/OpenAPICopyButton.tsx

@@ -0,0 +1,54 @@
+'use client';
+
+import { useState } from 'react';
+import { Button, type ButtonProps, Tooltip, TooltipTrigger } from 'react-aria-components';
+
+export function OpenAPICopyButton(
+    props: ButtonProps & {
+        value: string;
+    }
+) {
+    const { value } = props;
+    const { children, onPress, className } = props;
+    const [copied, setCopied] = useState(false);
+    const [isOpen, setIsOpen] = useState(false);
+
+    const handleCopy = () => {
+        if (!value) return;
+        navigator.clipboard.writeText(value).then(() => {
+            setIsOpen(true);
+            setCopied(true);
+
+            setTimeout(() => {
+                setCopied(false);
+            }, 2000);
+        });
+    };
+
+    return (
+        <TooltipTrigger isOpen={isOpen} onOpenChange={setIsOpen} closeDelay={200} delay={200}>
+            <Button
+                type="button"
+                preventFocusOnPress
+                onPress={(e) => {
+                    handleCopy();
+                    onPress?.(e);
+                }}
+                className={`openapi-copy-button ${className}`}
+                {...props}
+            >
+                {children}
+            </Button>
+
+            <Tooltip
+                isOpen={isOpen}
+                onOpenChange={setIsOpen}
+                placement="top"
+                offset={4}
+                className="openapi-tooltip"
+            >
+                {copied ? 'Copied' : 'Copy to clipboard'}{' '}
+            </Tooltip>
+        </TooltipTrigger>
+    );
+}

package/src/OpenAPIOperation.tsx

@@ -35,6 +35,7 @@ export function OpenAPIOperation(props: {
                           title: operation.summary,
                       })
                     : null}
+                <OpenAPIPath data={data} context={context} />
                 {operation.deprecated && <div className="openapi-deprecated">Deprecated</div>}
             </div>
             <div className="openapi-columns">
@@ -49,7 +50,6 @@ export function OpenAPIOperation(props: {
                         </div>
                     ) : null}
                     <OpenAPIOperationDescription operation={operation} context={context} />
-                    <OpenAPIPath data={data} context={context} />
                     <OpenAPISpec data={data} context={clientContext} />
                 </div>
                 <div className="openapi-column-preview">

package/src/OpenAPIPath.tsx

@@ -1,7 +1,6 @@
-import type { OpenAPIV3_1 } from '@gitbook/openapi-parser';
-import type React from 'react';
-import { ScalarApiButton } from './ScalarApiButton';
+import { OpenAPICopyButton } from './OpenAPICopyButton';
 import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
+import { getDefaultServerURL } from './util/server';
 
 /**
  * Display the path of an operation.
@@ -10,63 +9,62 @@ export function OpenAPIPath(props: {
     data: OpenAPIOperationData;
     context: OpenAPIContextProps;
 }) {
-    const { data, context } = props;
-    const { method, path } = data;
-    const { specUrl } = context;
-    const hideTryItPanel = data['x-hideTryItPanel'] || data.operation['x-hideTryItPanel'];
+    const { data } = props;
+    const { method, path, operation } = data;
+
+    const server = getDefaultServerURL(data.servers);
+    const formattedPath = formatPath(path);
 
     return (
         <div className="openapi-path">
             <div className={`openapi-method openapi-method-${method}`}>{method}</div>
-            <div className="openapi-path-title" data-deprecated={data.operation.deprecated}>
-                <p>{formatPath(path)}</p>
-            </div>
-            {!hideTryItPanel && validateHttpMethod(method) && (
-                <ScalarApiButton method={method} path={path} specUrl={specUrl} />
-            )}
+
+            <OpenAPICopyButton
+                value={server + path}
+                className="openapi-path-title"
+                data-deprecated={operation.deprecated}
+            >
+                <span className="openapi-path-server">{server}</span>
+                {formattedPath}
+            </OpenAPICopyButton>
         </div>
     );
 }
 
-function validateHttpMethod(method: string): method is OpenAPIV3_1.HttpMethods {
-    return ['get', 'post', 'put', 'delete', 'patch', 'head', 'options', 'trace'].includes(method);
-}
-
-// Format the path to highlight placeholders
+/**
+ * Format the path by wrapping placeholders in <span> tags.
+ */
 function formatPath(path: string) {
     // Matches placeholders like {id}, {userId}, etc.
-    const regex = /\{(\w+)\}/g;
+    const regex = /\{\s*(\w+)\s*\}|:\w+/g;
 
     const parts: (string | React.JSX.Element)[] = [];
     let lastIndex = 0;
 
-    // Replace placeholders with <em> tags
-    path.replace(regex, (match, key, offset) => {
-        parts.push(path.slice(lastIndex, offset));
-        parts.push(<em key={key}>{`{${key}}`}</em>);
+    //Wrap the variables in <span> tags and maintain either {variable} or :variable
+    path.replace(regex, (match, _, offset) => {
+        if (offset > lastIndex) {
+            parts.push(path.slice(lastIndex, offset));
+        }
+        parts.push(
+            <span key={offset} className="openapi-path-variable">
+                {match}
+            </span>
+        );
         lastIndex = offset + match.length;
         return match;
     });
 
-    // Push remaining text after the last placeholder
-    parts.push(path.slice(lastIndex));
-
-    // Join parts with separators wrapped in <span>
-    const formattedPath = parts.reduce(
-        (acc, part, index) => {
-            if (typeof part === 'string' && index > 0 && part === '/') {
-                acc.push(
-                    <span className="openapi-path-separator" key={`sep-${index}`}>
-                        /
-                    </span>
-                );
-            }
+    if (lastIndex < path.length) {
+        parts.push(path.slice(lastIndex));
+    }
 
-            acc.push(part);
-            return acc;
-        },
-        [] as (string | React.JSX.Element)[]
-    );
+    const formattedPath = parts.map((part, index) => {
+        if (typeof part === 'string') {
+            return <span key={index}>{part}</span>;
+        }
+        return part;
+    });
 
-    return <span>{formattedPath}</span>;
+    return formattedPath;
 }