@gitbook/react-openapi 0.5.0 → 0.7.0

package/src/OpenAPICodeSample.tsx

@@ -1,8 +1,8 @@
 import * as React from 'react';
 
 import { CodeSampleInput, codeSampleGenerators } from './code-samples';
-import { OpenAPIOperationData, toJSON } from './fetchOpenAPIOperation';
-import { generateMediaTypeExample } from './generateSchemaExample';
+import { OpenAPIOperationData } from './fetchOpenAPIOperation';
+import { generateMediaTypeExample, generateSchemaExample } from './generateSchemaExample';
 import { InteractiveSection } from './InteractiveSection';
 import { getServersURL } from './OpenAPIServerURL';
 import { ScalarApiButton } from './ScalarApiButton';
@@ -19,17 +19,51 @@ export function OpenAPICodeSample(props: {
 }) {
     const { data, context } = props;
 
+    const searchParams = new URLSearchParams();
+    const headersObject: { [k: string]: string } = {};
+
+    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: CodeSampleInput = {
-        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],
@@ -52,25 +86,32 @@ export function OpenAPICodeSample(props: {
     }> = null;
     (['x-custom-examples', 'x-code-samples', 'x-codeSamples'] as const).forEach((key) => {
         const customSamples = data.operation[key];
-        if (customSamples) {
-            customCodeSamples = customSamples.map((sample) => ({
-                key: `redocly-${sample.lang}`,
-                label: sample.label,
-                body: <context.CodeBlock code={sample.source} syntax={sample.lang} />,
-            }));
+        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: <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 (
         <InteractiveSection
             header="Request"
@@ -78,7 +119,7 @@ export function OpenAPICodeSample(props: {
             tabs={samples}
             overlay={
                 data['x-hideTryItPanel'] || data.operation['x-hideTryItPanel'] ? null : (
-                    <ScalarApiButton fetchOperationData={fetchOperationData} />
+                    <ScalarApiButton />
                 )
             }
         />

package/src/OpenAPIOperation.tsx

@@ -1,5 +1,6 @@
 import * as React from 'react';
 import classNames from 'classnames';
+import { ApiClientModalProvider } from '@scalar/api-client-react';
 
 import { OpenAPIOperationData, toJSON } from './fetchOpenAPIOperation';
 import { Markdown } from './Markdown';
@@ -7,7 +8,6 @@ import { OpenAPICodeSample } from './OpenAPICodeSample';
 import { OpenAPIResponseExample } from './OpenAPIResponseExample';
 import { OpenAPIServerURL } from './OpenAPIServerURL';
 import { OpenAPISpec } from './OpenAPISpec';
-import { ScalarApiClient } from './ScalarApiButton';
 import { OpenAPIClientContext, OpenAPIContextProps } from './types';
 
 /**
@@ -24,13 +24,19 @@ export function OpenAPIOperation(props: {
     const clientContext: OpenAPIClientContext = {
         defaultInteractiveOpened: context.defaultInteractiveOpened,
         icons: context.icons,
+        blockKey: context.blockKey,
     };
 
     return (
-        <ScalarApiClient>
+        <ApiClientModalProvider
+            configuration={{ spec: { url: context.specUrl } }}
+            initialRequest={{ path: data.path, method: data.method }}
+        >
             <div className={classNames('openapi-operation', className)}>
                 <div className="openapi-intro">
-                    <h2 className="openapi-summary">{operation.summary}</h2>
+                    <h2 className="openapi-summary" id={context.id}>
+                        {operation.summary}
+                    </h2>
                     {operation.description ? (
                         <Markdown className="openapi-description" source={operation.description} />
                     ) : null}
@@ -61,6 +67,6 @@ export function OpenAPIOperation(props: {
                     </div>
                 </div>
             </div>
-        </ScalarApiClient>
+        </ApiClientModalProvider>
     );
 }

package/src/OpenAPIResponseExample.tsx

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

package/src/OpenAPIResponses.tsx

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

package/src/OpenAPISchema.tsx

@@ -104,6 +104,11 @@ export function OpenAPISchemaProperty(
                             Example: <code>{JSON.stringify(schema.example)}</code>
                         </span>
                     ) : null}
+                    {schema.pattern ? (
+                        <div className="openapi-schema-pattern">
+                            Pattern: <code>{schema.pattern}</code>
+                        </div>
+                    ) : null}
                 </div>
             }
         >

package/src/ScalarApiButton.tsx

@@ -1,44 +1,17 @@
 'use client';
-import {
-    Cookie,
-    getHarRequest,
-    getParametersFromOperation,
-    type TransformedOperation,
-    getRequestFromOperation,
-    Query,
-    Header,
-    RequestBody,
-} from '@scalar/oas-utils';
-import React from 'react';
-
-import { OpenAPIOperationData, fromJSON } from './fetchOpenAPIOperation';
 
-const ApiClientReact = React.lazy(async () => {
-    const mod = await import('@scalar/api-client-react');
-    return { default: mod.ApiClientReact };
-});
-
-const ScalarContext = React.createContext<
-    (fetchOperationData: () => Promise<OpenAPIOperationData>) => void
->(() => {});
+import { useApiClientModal } from '@scalar/api-client-react';
+import React from 'react';
 
 /**
  * Button which launches the Scalar API Client
  */
-export function ScalarApiButton(props: {
-    fetchOperationData: () => Promise<OpenAPIOperationData>;
-}) {
-    const { fetchOperationData } = props;
-    const open = React.useContext(ScalarContext);
+export function ScalarApiButton() {
+    const client = useApiClientModal();
 
     return (
         <div className="scalar scalar-activate">
-            <button
-                className="scalar-activate-button"
-                onClick={() => {
-                    open(fetchOperationData);
-                }}
-            >
+            <button className="scalar-activate-button" onClick={() => client?.open()}>
                 <svg xmlns="http://www.w3.org/2000/svg" width="10" height="12" fill="none">
                     <path
                         stroke="currentColor"
@@ -51,109 +24,3 @@ export function ScalarApiButton(props: {
         </div>
     );
 }
-
-/**
- * Wrap the rendering with a context to open the scalar modal.
- */
-export function ScalarApiClient(props: { children: React.ReactNode }) {
-    const { children } = props;
-
-    const [active, setActive] = React.useState<null | {
-        operationData: OpenAPIOperationData | null;
-    }>(null);
-
-    const proxy = '/~scalar/proxy';
-
-    const open = React.useCallback(
-        async (fetchOperationData: () => Promise<OpenAPIOperationData>) => {
-            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,
-        } as TransformedOperation;
-
-        const variables = getParametersFromOperation(operation, 'path', false);
-
-        const request = getHarRequest(
-            {
-                url: operationData.path,
-            },
-            getRequestFromOperation(
-                {
-                    ...operation,
-                    information: {
-                        requestBody: operationData.operation.requestBody as RequestBody,
-                    },
-                },
-                { requiredOnly: false },
-            ),
-        );
-
-        return {
-            id: operationId,
-            type: operationData.method,
-            path: operationData.path,
-            variables,
-            cookies: request.cookies.map((cookie: Cookie) => {
-                return { ...cookie, enabled: true };
-            }),
-            query: request.queryString.map((queryString: Query) => {
-                const query: typeof queryString & { required?: boolean } = queryString;
-                return { ...queryString, enabled: query.required ?? true };
-            }),
-            headers: request.headers.map((header: Header) => {
-                return { ...header, enabled: true };
-            }),
-            url: operationData.servers[0]?.url,
-            body: request.postData?.text,
-        };
-    }, [active]);
-
-    return (
-        <ScalarContext.Provider value={open}>
-            {children}
-            {active ? (
-                <div className="scalar">
-                    <div className="scalar-container">
-                        <div className="scalar-app">
-                            <React.Suspense fallback={<ScalarLoading />}>
-                                <ApiClientReact
-                                    close={onClose}
-                                    proxy={proxy}
-                                    isOpen={true}
-                                    request={request}
-                                />
-                            </React.Suspense>
-                        </div>
-                        <div onClick={() => onClose()} className="scalar-app-exit"></div>
-                    </div>
-                </div>
-            ) : null}
-        </ScalarContext.Provider>
-    );
-}
-
-function ScalarLoading() {
-    return <div className="scalar-app-loading">Loading...</div>;
-}

package/src/code-samples.ts

@@ -65,6 +65,25 @@ export const codeSampleGenerators: CodeSampleGenerator[] = [
             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: string, spaces: number) {

package/src/fetchOpenAPIOperation.ts

@@ -43,7 +43,7 @@ export interface OpenAPICustomSpecProperties {
  */
 export interface OpenAPICustomOperationProperties {
     'x-code-samples'?: OpenAPICustomCodeSample[];
-    'x-codeSamples'?: OpenAPICustomCodeSample[];
+    'x-codeSamples'?: OpenAPICustomCodeSample[] | false;
     'x-custom-examples'?: OpenAPICustomCodeSample[];
 
     /**

package/src/generateSchemaExample.ts

@@ -104,7 +104,7 @@ export function generateSchemaExample(
 
     if (schema.properties) {
         const example: { [key: string]: JSONValue } = {};
-        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]);

package/src/types.ts

@@ -2,6 +2,9 @@ export type IconComponent = React.ComponentType<{ className?: string }>;
 
 export interface OpenAPIContextProps extends OpenAPIClientContext {
     CodeBlock: React.ComponentType<{ code: string; syntax: string }>;
+
+    /** Spec url for the Scalar Api Client */
+    specUrl: string;
 }
 
 export interface OpenAPIClientContext {
@@ -15,6 +18,12 @@ export interface OpenAPIClientContext {
      * @default false
      */
     defaultInteractiveOpened?: boolean;
+    /**
+     * The key of the block
+     */
+    blockKey?: string;
+    /** Optional id attached to the OpenAPI Operation heading and used as an anchor */
+    id?: string;
 }
 
 export interface OpenAPIFetcher {

package/src/utils.ts

@@ -7,3 +7,7 @@ export function noReference<T>(input: T | OpenAPIV3.ReferenceObject): T {
 
     return input;
 }
+
+export function createStateKey(key: string, scope?: string) {
+    return scope ? `${scope}_${key}` : key;
+}