@gitbook/react-openapi 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @gitbook/react-openapi
 
+## 0.7.0
+
+### Minor Changes
+
+-   cf3045a: Add Python support in Code Samples
+-   4247361: Add required query parameters to the code sample
+-   aa8c49e: Display pattern if available in parmas in OpenAPI block
+-   e914903: Synchronize response and response example tabs
+-   4cbcc5b: Rollback of scalar modal while fixing perf issue
+
+### Patch Changes
+
+-   51fa3ab: Adds content-visibility css property to OpenAPI Operation for better render performance
+-   f89b31c: Upgrade the scalar api client package
+-   094e9cd: bump: scalar from 1.0.5 to 1.0.7
+-   237b703: Fix crash when `example` is undefined for a response
+-   51955da: Adds tabs to Response Example section e.g. for status code examples
+-   a679e72: Render mandatory headers in code sample
+-   c079c3c: Update Scalar client to latest version
+
+## 0.6.0
+
+### Minor Changes
+
+-   709f1a1: Update Scalar to the latest version, with faster performances and an improved experience
+
+### Patch Changes
+
+-   ede2335: Fix x-codeSamples: false not working at the single operation level
+-   0426312: Fix tabs being empty for code samples when they are updated dynamically
+
 ## 0.5.0
 
 ### Minor Changes

package/dist/InteractiveSection.d.ts

@@ -1,4 +1,9 @@
 import React from 'react';
+interface InteractiveSectionTab {
+    key: string;
+    label: string;
+    body: React.ReactNode;
+}
 /**
  * To optimize rendering, most of the components are server-components,
  * and the interactiveness is mainly handled by a few key components like this one.
@@ -15,11 +20,7 @@ export declare function InteractiveSection(props: {
     toggleOpenIcon?: React.ReactNode;
     toggleCloseIcon?: React.ReactNode;
     /** Tabs of content to display */
-    tabs?: Array<{
-        key: string;
-        label: string;
-        body: React.ReactNode;
-    }>;
+    tabs?: Array<InteractiveSectionTab>;
     /** Default tab to have opened */
     defaultTab?: string;
     /** Content of the header */
@@ -28,4 +29,7 @@ export declare function InteractiveSection(props: {
     children?: React.ReactNode;
     /** Children to display within the container */
     overlay?: React.ReactNode;
+    /** An optional key referencing a value in global state */
+    stateKey?: string;
 }): React.JSX.Element;
+export {};

package/dist/InteractiveSection.js

@@ -1,15 +1,24 @@
 'use client';
 import classNames from 'classnames';
 import React from 'react';
+import { atom, useRecoilState } from 'recoil';
+const syncedTabsAtom = atom({
+    key: 'syncedTabState',
+    default: {},
+});
 /**
  * To optimize rendering, most of the components are server-components,
  * and the interactiveness is mainly handled by a few key components like this one.
  */
 export function InteractiveSection(props) {
-    const { id, className, toggeable = false, defaultOpened = true, tabs = [], defaultTab = tabs[0]?.key, header, children, overlay, toggleOpenIcon = '▶', toggleCloseIcon = '▼', } = props;
+    const { id, className, toggeable = false, defaultOpened = true, tabs = [], defaultTab = tabs[0]?.key, header, children, overlay, toggleOpenIcon = '▶', toggleCloseIcon = '▼', stateKey, } = props;
+    const [syncedTabs, setSyncedTabs] = useRecoilState(syncedTabsAtom);
+    const tabFromState = stateKey && stateKey in syncedTabs
+        ? tabs.find((tab) => tab.key === syncedTabs[stateKey])
+        : undefined;
     const [opened, setOpened] = React.useState(defaultOpened);
-    const [selectedTab, setSelectedTab] = React.useState(defaultTab);
-    const tabBody = tabs.find((tab) => tab.key === selectedTab)?.body;
+    const [selectedTabKey, setSelectedTab] = React.useState(tabFromState?.key ?? defaultTab);
+    const selectedTab = tabFromState ?? tabs.find((tab) => tab.key === selectedTabKey) ?? tabs[0];
     return (React.createElement("div", { id: id, className: classNames('openapi-section', toggeable ? 'openapi-section-toggeable' : null, className, toggeable ? `${className}-${opened ? 'opened' : 'closed'}` : null) },
         React.createElement("div", { onClick: () => {
                 if (toggeable) {
@@ -20,13 +29,19 @@ export function InteractiveSection(props) {
             React.createElement("div", { className: classNames('openapi-section-header-controls', `${className}-header-controls`), onClick: (event) => {
                     event.stopPropagation();
                 } },
-                tabs.length ? (React.createElement("select", { className: classNames('openapi-section-select', 'openapi-select', `${className}-tabs-select`), value: selectedTab, onChange: (event) => {
+                tabs.length ? (React.createElement("select", { className: classNames('openapi-section-select', 'openapi-select', `${className}-tabs-select`), value: selectedTab.key, onChange: (event) => {
                         setSelectedTab(event.target.value);
+                        if (stateKey) {
+                            setSyncedTabs((state) => ({
+                                ...state,
+                                [stateKey]: event.target.value,
+                            }));
+                        }
                         setOpened(true);
                     } }, tabs.map((tab) => (React.createElement("option", { key: tab.key, value: tab.key }, tab.label))))) : null,
-                (children || tabBody) && toggeable ? (React.createElement("button", { className: classNames('openapi-section-toggle', `${className}-toggle`), onClick: () => setOpened(!opened) }, opened ? toggleCloseIcon : toggleOpenIcon)) : null)),
-        (!toggeable || opened) && (children || tabBody) ? (React.createElement("div", { className: classNames('openapi-section-body', `${className}-body`) },
+                (children || selectedTab?.body) && toggeable ? (React.createElement("button", { className: classNames('openapi-section-toggle', `${className}-toggle`), onClick: () => setOpened(!opened) }, opened ? toggleCloseIcon : toggleOpenIcon)) : null)),
+        (!toggeable || opened) && (children || selectedTab?.body) ? (React.createElement("div", { className: classNames('openapi-section-body', `${className}-body`) },
             children,
-            tabBody)) : null,
+            selectedTab?.body)) : null,
         overlay));
 }

package/dist/OpenAPICodeSample.js

@@ -1,7 +1,6 @@
 import * as React from 'react';
 import { codeSampleGenerators } from './code-samples';
-import { toJSON } from './fetchOpenAPIOperation';
-import { generateMediaTypeExample } from './generateSchemaExample';
+import { generateMediaTypeExample, generateSchemaExample } from './generateSchemaExample';
 import { InteractiveSection } from './InteractiveSection';
 import { getServersURL } from './OpenAPIServerURL';
 import { ScalarApiButton } from './ScalarApiButton';
@@ -12,16 +11,44 @@ import { noReference } from './utils';
  */
 export function OpenAPICodeSample(props) {
     const { data, context } = props;
+    const searchParams = new URLSearchParams();
+    const headersObject = {};
+    data.operation.parameters?.forEach((rawParam) => {
+        const param = noReference(rawParam);
+        if (!param) {
+            return;
+        }
+        if (param.in === 'header' && param.required) {
+            const example = param.schema
+                ? generateSchemaExample(noReference(param.schema))
+                : undefined;
+            if (example !== undefined) {
+                headersObject[param.name] =
+                    typeof example !== 'string' ? JSON.stringify(example) : example;
+            }
+        }
+        else if (param.in === 'query' && param.required) {
+            const example = param.schema
+                ? generateSchemaExample(noReference(param.schema))
+                : undefined;
+            if (example !== undefined) {
+                searchParams.append(param.name, String(Array.isArray(example) ? example[0] : example));
+            }
+        }
+    });
     const requestBody = noReference(data.operation.requestBody);
     const requestBodyContent = requestBody ? Object.entries(requestBody.content)[0] : undefined;
     const input = {
-        url: getServersURL(data.servers) + data.path,
+        url: getServersURL(data.servers) +
+            data.path +
+            (searchParams.size ? `?${searchParams.toString()}` : ''),
         method: data.method,
         body: requestBodyContent
             ? generateMediaTypeExample(requestBodyContent[1], { onlyRequired: true })
             : undefined,
         headers: {
             ...getSecurityHeaders(data.securities),
+            ...headersObject,
             ...(requestBodyContent
                 ? {
                     'Content-Type': requestBodyContent[0],
@@ -38,23 +65,28 @@ export function OpenAPICodeSample(props) {
     let customCodeSamples = null;
     ['x-custom-examples', 'x-code-samples', 'x-codeSamples'].forEach((key) => {
         const customSamples = data.operation[key];
-        if (customSamples) {
-            customCodeSamples = customSamples.map((sample) => ({
+        if (customSamples && Array.isArray(customSamples)) {
+            customCodeSamples = customSamples
+                .filter((sample) => {
+                return (typeof sample.label === 'string' &&
+                    typeof sample.source === 'string' &&
+                    typeof sample.lang === 'string');
+            })
+                .map((sample) => ({
                 key: `redocly-${sample.lang}`,
                 label: sample.label,
                 body: React.createElement(context.CodeBlock, { code: sample.source, syntax: sample.lang }),
             }));
         }
     });
-    const samples = customCodeSamples ?? (data['x-codeSamples'] !== false ? autoCodeSamples : []);
+    // 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;
     }
-    async function fetchOperationData() {
-        'use server';
-        return toJSON(data);
-    }
-    return (React.createElement(InteractiveSection, { header: "Request", className: "openapi-codesample", tabs: samples, overlay: data['x-hideTryItPanel'] || data.operation['x-hideTryItPanel'] ? null : (React.createElement(ScalarApiButton, { fetchOperationData: fetchOperationData })) }));
+    return (React.createElement(InteractiveSection, { header: "Request", className: "openapi-codesample", tabs: samples, overlay: data['x-hideTryItPanel'] || data.operation['x-hideTryItPanel'] ? null : (React.createElement(ScalarApiButton, null)) }));
 }
 function getSecurityHeaders(securities) {
     const security = securities[0];

package/dist/OpenAPIOperation.js

@@ -1,12 +1,12 @@
 import * as React from 'react';
 import classNames from 'classnames';
+import { ApiClientModalProvider } from '@scalar/api-client-react';
 import { toJSON } from './fetchOpenAPIOperation';
 import { Markdown } from './Markdown';
 import { OpenAPICodeSample } from './OpenAPICodeSample';
 import { OpenAPIResponseExample } from './OpenAPIResponseExample';
 import { OpenAPIServerURL } from './OpenAPIServerURL';
 import { OpenAPISpec } from './OpenAPISpec';
-import { ScalarApiClient } from './ScalarApiButton';
 /**
  * Display an interactive OpenAPI operation.
  */
@@ -16,11 +16,12 @@ export function OpenAPIOperation(props) {
     const clientContext = {
         defaultInteractiveOpened: context.defaultInteractiveOpened,
         icons: context.icons,
+        blockKey: context.blockKey,
     };
-    return (React.createElement(ScalarApiClient, null,
+    return (React.createElement(ApiClientModalProvider, { configuration: { spec: { url: context.specUrl } }, initialRequest: { path: data.path, method: data.method } },
         React.createElement("div", { className: classNames('openapi-operation', className) },
             React.createElement("div", { className: "openapi-intro" },
-                React.createElement("h2", { className: "openapi-summary" }, operation.summary),
+                React.createElement("h2", { className: "openapi-summary", id: context.id }, operation.summary),
                 operation.description ? (React.createElement(Markdown, { className: "openapi-description", source: operation.description })) : null,
                 React.createElement("div", { className: "openapi-target" },
                     React.createElement("span", { className: classNames('openapi-method', `openapi-method-${method.toLowerCase()}`) }, method.toUpperCase()),

package/dist/OpenAPIResponseExample.js

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { InteractiveSection } from './InteractiveSection';
 import { generateSchemaExample } from './generateSchemaExample';
-import { noReference } from './utils';
+import { createStateKey, noReference } from './utils';
 /**
  * Display an example of the response content.
  */
@@ -28,21 +28,27 @@ export function OpenAPIResponseExample(props) {
         }
         return Number(a) - Number(b);
     });
-    // Take the first one
-    const response = responses[0];
-    if (!response) {
-        return null;
-    }
-    const responseObject = noReference(response[1]);
-    const schema = noReference((responseObject.content?.['application/json'] ??
-        responseObject.content?.[Object.keys(responseObject.content)[0]])?.schema);
-    if (!schema) {
-        return null;
-    }
-    const example = generateSchemaExample(schema);
-    if (example === undefined) {
+    const examples = responses
+        .map((response) => {
+        const responseObject = noReference(response[1]);
+        const schema = noReference((responseObject.content?.['application/json'] ??
+            responseObject.content?.[Object.keys(responseObject.content)[0]])?.schema);
+        if (!schema) {
+            return null;
+        }
+        const example = generateSchemaExample(schema);
+        if (example === undefined) {
+            return null;
+        }
+        return {
+            key: `${response[0]}`,
+            label: `${response[0]}`,
+            body: (React.createElement(context.CodeBlock, { code: typeof example === 'string' ? example : JSON.stringify(example, null, 2), syntax: "json" })),
+        };
+    })
+        .filter((val) => Boolean(val));
+    if (examples.length === 0) {
         return null;
     }
-    return (React.createElement(InteractiveSection, { header: "Response", className: "openapi-response-example" },
-        React.createElement(context.CodeBlock, { code: typeof example === 'string' ? example : JSON.stringify(example, null, 2), syntax: "json" })));
+    return (React.createElement(InteractiveSection, { stateKey: createStateKey('response', context.blockKey), header: "Response", className: "openapi-response-example", tabs: examples }));
 }

package/dist/OpenAPIResponses.js

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import classNames from 'classnames';
-import { noReference } from './utils';
+import { createStateKey, noReference } from './utils';
 import { OpenAPIResponse } from './OpenAPIResponse';
 import { InteractiveSection } from './InteractiveSection';
 /**
@@ -8,7 +8,7 @@ import { InteractiveSection } from './InteractiveSection';
  */
 export function OpenAPIResponses(props) {
     const { responses, context } = props;
-    return (React.createElement(InteractiveSection, { header: "Response", className: classNames('openapi-responses'), tabs: Object.entries(responses).map(([statusCode, response]) => {
+    return (React.createElement(InteractiveSection, { stateKey: createStateKey('response', context.blockKey), header: "Response", className: classNames('openapi-responses'), tabs: Object.entries(responses).map(([statusCode, response]) => {
             return {
                 key: statusCode,
                 label: statusCode,

package/dist/OpenAPISchema.js

@@ -34,7 +34,10 @@ export function OpenAPISchemaProperty(props) {
             schema.description ? (React.createElement(Markdown, { source: schema.description, className: "openapi-schema-description" })) : null,
             shouldDisplayExample(schema) ? (React.createElement("span", { className: "openapi-schema-example" },
                 "Example: ",
-                React.createElement("code", null, JSON.stringify(schema.example)))) : null) }, (properties && properties.length > 0) ||
+                React.createElement("code", null, JSON.stringify(schema.example)))) : null,
+            schema.pattern ? (React.createElement("div", { className: "openapi-schema-pattern" },
+                "Pattern: ",
+                React.createElement("code", null, schema.pattern))) : null) }, (properties && properties.length > 0) ||
         (schema.enum && schema.enum.length > 0) ||
         parentCircularRef ? (React.createElement(React.Fragment, null,
         properties?.length ? (React.createElement(OpenAPISchemaProperties, { properties: properties, circularRefs: circularRefs, context: context })) : null,

package/dist/ScalarApiButton.d.ts

@@ -1,14 +1,5 @@
 import React from 'react';
-import { OpenAPIOperationData } from './fetchOpenAPIOperation';
 /**
  * Button which launches the Scalar API Client
  */
-export declare function ScalarApiButton(props: {
-    fetchOperationData: () => Promise<OpenAPIOperationData>;
-}): React.JSX.Element;
-/**
- * Wrap the rendering with a context to open the scalar modal.
- */
-export declare function ScalarApiClient(props: {
-    children: React.ReactNode;
-}): React.JSX.Element;
+export declare function ScalarApiButton(): React.JSX.Element;

package/dist/ScalarApiButton.js

@@ -1,89 +1,14 @@
 'use client';
-import { getHarRequest, getParametersFromOperation, getRequestFromOperation, } from '@scalar/oas-utils';
+import { useApiClientModal } from '@scalar/api-client-react';
 import React from 'react';
-import { fromJSON } from './fetchOpenAPIOperation';
-const ApiClientReact = React.lazy(async () => {
-    const mod = await import('@scalar/api-client-react');
-    return { default: mod.ApiClientReact };
-});
-const ScalarContext = React.createContext(() => { });
 /**
  * Button which launches the Scalar API Client
  */
-export function ScalarApiButton(props) {
-    const { fetchOperationData } = props;
-    const open = React.useContext(ScalarContext);
+export function ScalarApiButton() {
+    const client = useApiClientModal();
     return (React.createElement("div", { className: "scalar scalar-activate" },
-        React.createElement("button", { className: "scalar-activate-button", onClick: () => {
-                open(fetchOperationData);
-            } },
+        React.createElement("button", { className: "scalar-activate-button", onClick: () => client?.open() },
             React.createElement("svg", { xmlns: "http://www.w3.org/2000/svg", width: "10", height: "12", fill: "none" },
                 React.createElement("path", { stroke: "currentColor", strokeWidth: "1.5", d: "M1 10.05V1.43c0-.2.2-.31.37-.22l7.26 4.08c.17.1.17.33.01.43l-7.26 4.54a.25.25 0 0 1-.38-.21Z" })),
             "Test it")));
 }
-/**
- * Wrap the rendering with a context to open the scalar modal.
- */
-export function ScalarApiClient(props) {
-    const { children } = props;
-    const [active, setActive] = React.useState(null);
-    const proxy = '/~scalar/proxy';
-    const open = React.useCallback(async (fetchOperationData) => {
-        setActive({ operationData: null });
-        const operationData = fromJSON(await fetchOperationData());
-        setActive({ operationData });
-    }, []);
-    const onClose = React.useCallback(() => {
-        setActive(null);
-    }, []);
-    const request = React.useMemo(() => {
-        const operationData = active?.operationData;
-        if (!operationData) {
-            return null;
-        }
-        const operationId = operationData.operation.operationId ?? operationData.method + operationData.path;
-        const operation = {
-            ...operationData,
-            httpVerb: operationData.method,
-            pathParameters: operationData.operation.parameters,
-        };
-        const variables = getParametersFromOperation(operation, 'path', false);
-        const request = getHarRequest({
-            url: operationData.path,
-        }, getRequestFromOperation({
-            ...operation,
-            information: {
-                requestBody: operationData.operation.requestBody,
-            },
-        }, { requiredOnly: false }));
-        return {
-            id: operationId,
-            type: operationData.method,
-            path: operationData.path,
-            variables,
-            cookies: request.cookies.map((cookie) => {
-                return { ...cookie, enabled: true };
-            }),
-            query: request.queryString.map((queryString) => {
-                const query = queryString;
-                return { ...queryString, enabled: query.required ?? true };
-            }),
-            headers: request.headers.map((header) => {
-                return { ...header, enabled: true };
-            }),
-            url: operationData.servers[0]?.url,
-            body: request.postData?.text,
-        };
-    }, [active]);
-    return (React.createElement(ScalarContext.Provider, { value: open },
-        children,
-        active ? (React.createElement("div", { className: "scalar" },
-            React.createElement("div", { className: "scalar-container" },
-                React.createElement("div", { className: "scalar-app" },
-                    React.createElement(React.Suspense, { fallback: React.createElement(ScalarLoading, null) },
-                        React.createElement(ApiClientReact, { close: onClose, proxy: proxy, isOpen: true, request: request }))),
-                React.createElement("div", { onClick: () => onClose(), className: "scalar-app-exit" })))) : null));
-}
-function ScalarLoading() {
-    return React.createElement("div", { className: "scalar-app-loading" }, "Loading...");
-}

package/dist/code-samples.js

@@ -40,6 +40,25 @@ export const codeSampleGenerators = [
             return lines.map((line, index) => (index > 0 ? indent(line, 2) : line)).join(separator);
         },
     },
+    {
+        id: 'python',
+        label: 'Python',
+        syntax: 'python',
+        generate: ({ method, url, headers, body }) => {
+            let code = 'import requests\n\n';
+            code += `response = requests.${method.toLowerCase()}(\n`;
+            code += indent(`"${url}",\n`, 4);
+            if (headers) {
+                code += indent(`headers=${JSON.stringify(headers)},\n`, 4);
+            }
+            if (body) {
+                code += indent(`json=${JSON.stringify(body)}\n`, 4);
+            }
+            code += ')\n';
+            code += `data = response.json()`;
+            return code;
+        },
+    },
 ];
 function indent(code, spaces) {
     const indent = ' '.repeat(spaces);

package/dist/fetchOpenAPIOperation.d.ts

@@ -32,7 +32,7 @@ export interface OpenAPICustomSpecProperties {
  */
 export interface OpenAPICustomOperationProperties {
     'x-code-samples'?: OpenAPICustomCodeSample[];
-    'x-codeSamples'?: OpenAPICustomCodeSample[];
+    'x-codeSamples'?: OpenAPICustomCodeSample[] | false;
     'x-custom-examples'?: OpenAPICustomCodeSample[];
     /**
      * If `true`, the "Try it" button will not be displayed.

package/dist/generateSchemaExample.js

@@ -70,7 +70,7 @@ export function generateSchemaExample(schema, options = {}, ancestors = new Set(
     }
     if (schema.properties) {
         const example = {};
-        const props = onlyRequired ? schema.required ?? [] : Object.keys(schema.properties);
+        const props = onlyRequired ? (schema.required ?? []) : Object.keys(schema.properties);
         for (const key of props) {
             const property = noReference(schema.properties[key]);
             if (property && (onlyRequired || !property.deprecated)) {