@gitbook/react-openapi 0.7.1 → 1.0.1

package/src/OpenAPISpec.tsx

@@ -1,16 +1,14 @@
 'use client';
 
-import * as React from 'react';
-import { OpenAPIV3 } from 'openapi-types';
+import type { OpenAPI } from '@gitbook/openapi-parser';
 
-import { OpenAPIOperationData, fromJSON } from './fetchOpenAPIOperation';
 import { InteractiveSection } from './InteractiveSection';
 import { OpenAPIRequestBody } from './OpenAPIRequestBody';
 import { OpenAPIResponses } from './OpenAPIResponses';
 import { OpenAPISchemaProperties } from './OpenAPISchema';
 import { OpenAPISecurities } from './OpenAPISecurities';
-import { OpenAPIClientContext } from './types';
-import { noReference } from './utils';
+import type { OpenAPIClientContext, OpenAPIOperationData } from './types';
+import { resolveDescription } from './utils';
 
 /**
  * Client component to render the spec for the request and response.
@@ -18,13 +16,13 @@ import { noReference } from './utils';
  * We use a client component as rendering recursive JSON schema in the server is expensive
  * (the entire schema is rendered at once, while the client component only renders the visible part)
  */
-export function OpenAPISpec(props: { rawData: any; context: OpenAPIClientContext }) {
-    const { rawData, context } = props;
+export function OpenAPISpec(props: { data: OpenAPIOperationData; context: OpenAPIClientContext }) {
+    const { data, context } = props;
 
-    const parsedData = fromJSON(rawData) as OpenAPIOperationData;
-    const { operation, securities } = parsedData;
+    const { operation, securities } = data;
 
-    const parameterGroups = groupParameters((operation.parameters || []).map(noReference));
+    const parameters = operation.parameters ?? [];
+    const parameterGroups = groupParameters(parameters);
 
     return (
         <>
@@ -32,73 +30,75 @@ export function OpenAPISpec(props: { rawData: any; context: OpenAPIClientContext
                 <OpenAPISecurities securities={securities} context={context} />
             ) : null}
 
-            {parameterGroups.map((group) => (
-                <InteractiveSection
-                    key={group.key}
-                    className="openapi-parameters"
-                    toggeable
-                    toggleOpenIcon={context.icons.chevronRight}
-                    toggleCloseIcon={context.icons.chevronDown}
-                    header={group.label}
-                    defaultOpened={group.key === 'path' || context.defaultInteractiveOpened}
-                >
-                    <OpenAPISchemaProperties
-                        properties={group.parameters.map((parameter) => ({
-                            propertyName: parameter.name,
-                            schema: {
-                                // Description of the parameter is defined at the parameter level
-                                // we use display it if the schema doesn't override it
-                                description: parameter.description,
-                                example: parameter.example,
-                                ...(noReference(parameter.schema) ?? {}),
-                            },
-                            required: parameter.required,
-                        }))}
-                        context={context}
-                    />
-                </InteractiveSection>
-            ))}
+            {parameterGroups.map((group) => {
+                return (
+                    <InteractiveSection
+                        key={group.key}
+                        className="openapi-parameters"
+                        header={group.label}
+                    >
+                        <OpenAPISchemaProperties
+                            properties={group.parameters.map((parameter) => {
+                                const description = resolveDescription(parameter);
+                                return {
+                                    propertyName: parameter.name,
+                                    schema: {
+                                        // Description of the parameter is defined at the parameter level
+                                        // we use display it if the schema doesn't override it
+                                        description: description,
+                                        example: parameter.example,
+                                        // Deprecated can be defined at the parameter level
+                                        deprecated: parameter.deprecated,
+                                        ...(parameter.schema ?? {}),
+                                    },
+                                    required: parameter.required,
+                                };
+                            })}
+                            context={context}
+                        />
+                    </InteractiveSection>
+                );
+            })}
 
             {operation.requestBody ? (
-                <OpenAPIRequestBody
-                    requestBody={noReference(operation.requestBody)}
-                    context={context}
-                />
+                <OpenAPIRequestBody requestBody={operation.requestBody} context={context} />
             ) : null}
             {operation.responses ? (
-                <OpenAPIResponses responses={noReference(operation.responses)} context={context} />
+                <OpenAPIResponses responses={operation.responses} context={context} />
             ) : null}
         </>
     );
 }
 
-function groupParameters(parameters: OpenAPIV3.ParameterObject[]): Array<{
+function groupParameters(parameters: OpenAPI.Parameters): Array<{
     key: string;
     label: string;
-    parameters: OpenAPIV3.ParameterObject[];
+    parameters: OpenAPI.Parameters;
 }> {
     const sorted = ['path', 'query', 'header'];
 
     const groups: Array<{
         key: string;
         label: string;
-        parameters: OpenAPIV3.ParameterObject[];
+        parameters: OpenAPI.Parameters;
     }> = [];
 
-    parameters.forEach((parameter) => {
-        const key = parameter.in;
-        const label = getParameterGroupName(parameter.in);
-        const group = groups.find((group) => group.key === key);
-        if (group) {
-            group.parameters.push(parameter);
-        } else {
-            groups.push({
-                key,
-                label,
-                parameters: [parameter],
-            });
-        }
-    });
+    parameters
+        .filter((parameter) => parameter.in)
+        .forEach((parameter) => {
+            const key = parameter.in;
+            const label = getParameterGroupName(parameter.in);
+            const group = groups.find((group) => group.key === key);
+            if (group) {
+                group.parameters.push(parameter);
+            } else {
+                groups.push({
+                    key,
+                    label,
+                    parameters: [parameter],
+                });
+            }
+        });
 
     groups.sort((a, b) => sorted.indexOf(a.key) - sorted.indexOf(b.key));
 

package/src/OpenAPITabs.tsx

@@ -0,0 +1,153 @@
+'use client';
+
+import { createContext, useContext, useEffect, useMemo, useState } from 'react';
+import { Key, Tab, TabList, TabPanel, Tabs, TabsProps } from 'react-aria-components';
+import { Markdown } from './Markdown';
+import { useSyncedTabsGlobalState } from './useSyncedTabsGlobalState';
+import { useIntersectionObserver } from 'usehooks-ts';
+
+export type Tab = {
+    key: Key;
+    label: string;
+    body: React.ReactNode;
+    description?: string;
+};
+
+type OpenAPITabsContextData = {
+    items: Tab[];
+    selectedTab: Tab;
+};
+
+const OpenAPITabsContext = createContext<OpenAPITabsContextData | null>(null);
+
+function useOpenAPITabsContext() {
+    const context = useContext(OpenAPITabsContext);
+    if (!context) {
+        throw new Error('OpenAPITabsContext is missing');
+    }
+    return context;
+}
+
+/**
+ * The OpenAPI Tabs wrapper component.
+ */
+export function OpenAPITabs(
+    props: React.PropsWithChildren<TabsProps & { items: Tab[]; stateKey?: string }>,
+) {
+    const { children, items, stateKey } = props;
+    const isVisible = stateKey
+        ? useIntersectionObserver({
+              threshold: 0.1,
+              rootMargin: '200px',
+          })
+        : true;
+    const defaultTab = items[0] as Tab;
+    const [syncedTabs, setSyncedTabs] = useSyncedTabsGlobalState<Tab>();
+    const [selectedTabKey, setSelectedTabKey] = useState(() => {
+        if (isVisible && stateKey && syncedTabs && syncedTabs.has(stateKey)) {
+            const tabFromState = syncedTabs.get(stateKey);
+            return tabFromState?.key ?? items[0]?.key;
+        }
+        return items[0]?.key;
+    });
+    const [selectedTab, setSelectedTab] = useState<Tab>(defaultTab);
+
+    const handleSelectionChange = (key: Key) => {
+        setSelectedTabKey(key);
+        if (stateKey) {
+            const tab = items.find((item) => item.key === key);
+
+            if (!tab) {
+                return;
+            }
+
+            setSyncedTabs((state) => {
+                const newState = new Map(state);
+                newState.set(stateKey, tab);
+                return newState;
+            });
+        }
+    };
+
+    useEffect(() => {
+        if (isVisible && stateKey && syncedTabs && syncedTabs.has(stateKey)) {
+            const tabFromState = syncedTabs.get(stateKey);
+
+            if (!items.some((item) => item.key === tabFromState?.key)) {
+                return;
+            }
+
+            if (tabFromState && tabFromState?.key !== selectedTab?.key) {
+                setSelectedTab(tabFromState);
+            }
+        }
+    }, [isVisible, stateKey, syncedTabs, selectedTabKey]);
+
+    const contextValue = useMemo(() => ({ items, selectedTab }), [items, selectedTab]);
+
+    return (
+        <OpenAPITabsContext.Provider value={contextValue}>
+            <Tabs
+                className="openapi-tabs"
+                onSelectionChange={handleSelectionChange}
+                selectedKey={selectedTab?.key}
+            >
+                {children}
+            </Tabs>
+        </OpenAPITabsContext.Provider>
+    );
+}
+
+/**
+ * The OpenAPI Tabs list component.
+ * This component should be used as a child of the OpenAPITabs component.
+ * It renders the list of tabs.
+ */
+export function OpenAPITabsList() {
+    const { items } = useOpenAPITabsContext();
+
+    return (
+        <TabList className="openapi-tabs-list">
+            {items.map((tab) => (
+                <Tab
+                    style={({ isFocusVisible }) => ({
+                        outline: isFocusVisible
+                            ? '2px solid rgb(var(--primary-color-500)/0.4)'
+                            : 'none',
+                    })}
+                    className="openapi-tabs-tab"
+                    key={`Tab-${tab.key}`}
+                    id={tab.key}
+                >
+                    {tab.label}
+                </Tab>
+            ))}
+        </TabList>
+    );
+}
+
+/**
+ * The OpenAPI Tabs panels component.
+ * This component should be used as a child of the OpenAPITabs component.
+ * It renders the content of the selected tab.
+ */
+export function OpenAPITabsPanels() {
+    const { selectedTab } = useOpenAPITabsContext();
+
+    if (!selectedTab) {
+        return null;
+    }
+
+    return (
+        <TabPanel
+            key={`TabPanel-${selectedTab.key}`}
+            id={selectedTab.key.toString()}
+            className="openapi-tabs-panel"
+        >
+            {selectedTab.body}
+            {selectedTab.description ? (
+                <Markdown source={selectedTab.description} className="openapi-tabs-footer" />
+            ) : null}
+        </TabPanel>
+    );
+}

package/src/ScalarApiButton.tsx

@@ -1,19 +1,34 @@
 'use client';
 
-import { useApiClientModal } from '@scalar/api-client-react';
-import React from 'react';
+import { ApiClientModalProvider, useApiClientModal } from '@scalar/api-client-react';
+import { useEffect, useImperativeHandle, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+
+import { useOpenAPIOperationContext } from './OpenAPIOperationContext';
+import { useEventCallback } from 'usehooks-ts';
 
 /**
  * Button which launches the Scalar API Client
  */
-export function ScalarApiButton({ method, path }: { method: string; path: string }) {
-    const client = useApiClientModal();
-
+export function ScalarApiButton({
+    method,
+    path,
+    specUrl,
+}: {
+    method: string;
+    path: string;
+    specUrl: string;
+}) {
+    const [isOpen, setIsOpen] = useState(false);
+    const controllerRef = useRef<ScalarModalControllerRef>(null);
     return (
         <div className="scalar scalar-activate">
             <button
-                className="scalar-activate-button"
-                onClick={() => client?.open({ method, path })}
+                className="scalar-activate-button button"
+                onClick={() => {
+                    controllerRef.current?.openClient?.();
+                    setIsOpen(true);
+                }}
             >
                 <svg xmlns="http://www.w3.org/2000/svg" width="10" height="12" fill="none">
                     <path
@@ -24,6 +39,68 @@ export function ScalarApiButton({ method, path }: { method: string; path: string
                 </svg>
                 Test it
             </button>
+
+            {isOpen &&
+                createPortal(
+                    <ScalarModal
+                        controllerRef={controllerRef}
+                        method={method}
+                        path={path}
+                        specUrl={specUrl}
+                    />,
+                    document.body,
+                )}
         </div>
     );
 }
+
+function ScalarModal(props: {
+    method: string;
+    path: string;
+    specUrl: string;
+    controllerRef: React.Ref<ScalarModalControllerRef>;
+}) {
+    return (
+        <ApiClientModalProvider
+            configuration={{ spec: { url: props.specUrl } }}
+            initialRequest={{ path: props.path, method: props.method }}
+        >
+            <ScalarModalController
+                method={props.method}
+                path={props.path}
+                controllerRef={props.controllerRef}
+            />
+        </ApiClientModalProvider>
+    );
+}
+
+type ScalarModalControllerRef = {
+    openClient: (() => void) | undefined;
+};
+
+function ScalarModalController(props: {
+    method: string;
+    path: string;
+    controllerRef: React.Ref<ScalarModalControllerRef>;
+}) {
+    const client = useApiClientModal();
+    const openClient = client?.open;
+    useImperativeHandle(
+        props.controllerRef,
+        () => ({ openClient: openClient ? () => openClient() : undefined }),
+        [openClient],
+    );
+
+    // Open the client when the component is mounted.
+    const { onOpenClient } = useOpenAPIOperationContext();
+    const trackOpening = useEventCallback(() => {
+        onOpenClient({ method: props.method, path: props.path });
+    });
+    useEffect(() => {
+        if (openClient) {
+            openClient();
+            trackOpening();
+        }
+    }, [openClient]);
+    return null;
+}

package/src/code-samples.test.ts

@@ -0,0 +1,51 @@
+import { it, expect } from 'bun:test';
+import { parseHostAndPath } from './code-samples';
+
+it('should parse host and path on url strings properly', () => {
+    const testUrls = [
+        '//example.com/path',
+        '//sub.example.com',
+        '//example:8080/v1/test',
+        'ftp://domain.com',
+        '//example.com/com.example',
+        'https://example.com/path.com/another.com',
+        'example.com/firstPath/secondPath',
+    ];
+
+    expect(testUrls.map(parseHostAndPath)).toEqual([
+        {
+            host: 'example.com',
+            path: '/path',
+        },
+
+        {
+            host: 'sub.example.com',
+            path: '/',
+        },
+
+        {
+            host: 'example:8080',
+            path: '/v1/test',
+        },
+
+        {
+            host: 'domain.com',
+            path: '/',
+        },
+
+        {
+            host: 'example.com',
+            path: '/com.example',
+        },
+
+        {
+            host: 'example.com',
+            path: '/path.com/another.com',
+        },
+
+        {
+            host: 'example.com',
+            path: '/firstPath/secondPath',
+        },
+    ]);
+});

package/src/code-samples.ts

@@ -1,3 +1,5 @@
+import { stringifyOpenAPI } from './stringifyOpenAPI';
+
 export interface CodeSampleInput {
     method: string;
     url: string;
@@ -14,55 +16,55 @@ interface CodeSampleGenerator {
 
 export const codeSampleGenerators: CodeSampleGenerator[] = [
     {
-        id: 'javascript',
-        label: 'JavaScript',
-        syntax: 'javascript',
+        id: 'curl',
+        label: 'cURL',
+        syntax: 'bash',
         generate: ({ method, url, headers, body }) => {
-            let code = '';
+            const separator = ' \\\n';
 
-            code += `const response = await fetch('${url}', {
-    method: '${method.toUpperCase()}',\n`;
+            const lines: string[] = ['curl -L'];
 
-            if (headers) {
-                code += indent(`headers: ${JSON.stringify(headers, null, 2)},\n`, 4);
+            if (method.toUpperCase() !== 'GET') {
+                lines.push(`--request ${method.toUpperCase()}`);
             }
 
-            if (body) {
-                code += indent(`body: JSON.stringify(${JSON.stringify(body, null, 2)}),\n`, 4);
+            lines.push(`--url '${url}'`);
+
+            if (headers) {
+                Object.entries(headers).forEach(([key, value]) => {
+                    lines.push(`--header '${key}: ${value}'`);
+                });
             }
 
-            code += `});\n`;
-            code += `const data = await response.json();`;
+            if (body && Object.keys(body).length > 0) {
+                lines.push(`--data '${stringifyOpenAPI(body)}'`);
+            }
 
-            return code;
+            return lines.map((line, index) => (index > 0 ? indent(line, 2) : line)).join(separator);
         },
     },
     {
-        id: 'curl',
-        label: 'Curl',
-        syntax: 'bash',
+        id: 'javascript',
+        label: 'JavaScript',
+        syntax: 'javascript',
         generate: ({ method, url, headers, body }) => {
-            const separator = ' \\\n';
-
-            const lines: string[] = ['curl -L'];
+            let code = '';
 
-            if (method.toUpperCase() !== 'GET') {
-                lines.push(`-X ${method.toUpperCase()}`);
-            }
+            code += `const response = await fetch('${url}', {
+    method: '${method.toUpperCase()}',\n`;
 
             if (headers) {
-                Object.entries(headers).forEach(([key, value]) => {
-                    lines.push(`-H '${key}: ${value}'`);
-                });
+                code += indent(`headers: ${stringifyOpenAPI(headers, null, 2)},\n`, 4);
             }
 
-            lines.push(`'${url}'`);
-
             if (body) {
-                lines.push(`-d '${JSON.stringify(body)}'`);
+                code += indent(`body: JSON.stringify(${stringifyOpenAPI(body, null, 2)}),\n`, 4);
             }
 
-            return lines.map((line, index) => (index > 0 ? indent(line, 2) : line)).join(separator);
+            code += `});\n`;
+            code += `const data = await response.json();`;
+
+            return code;
         },
     },
     {
@@ -74,16 +76,56 @@ export const codeSampleGenerators: CodeSampleGenerator[] = [
             code += `response = requests.${method.toLowerCase()}(\n`;
             code += indent(`"${url}",\n`, 4);
             if (headers) {
-                code += indent(`headers=${JSON.stringify(headers)},\n`, 4);
+                code += indent(`headers=${stringifyOpenAPI(headers)},\n`, 4);
             }
             if (body) {
-                code += indent(`json=${JSON.stringify(body)}\n`, 4);
+                code += indent(`json=${stringifyOpenAPI(body)}\n`, 4);
             }
             code += ')\n';
             code += `data = response.json()`;
             return code;
         },
     },
+    {
+        id: 'http',
+        label: 'HTTP',
+        syntax: 'bash',
+        generate: ({ method, url, headers = {}, body }: CodeSampleInput) => {
+            const { host, path } = parseHostAndPath(url);
+
+            if (body) {
+                // if we had a body add a content length header
+                const bodyContent = body ? stringifyOpenAPI(body) : '';
+                // handle unicode chars with a text encoder
+                const encoder = new TextEncoder();
+
+                headers = {
+                    ...headers,
+                    'Content-Length': encoder.encode(bodyContent).length.toString(),
+                };
+            }
+
+            if (!headers.hasOwnProperty('Accept')) {
+                headers.Accept = '*/*';
+            }
+
+            const headerString = headers
+                ? Object.entries(headers)
+                      .map(([key, value]) =>
+                          key.toLowerCase() !== 'host' ? `${key}: ${value}` : ``,
+                      )
+                      .join('\n') + '\n'
+                : '';
+
+            const bodyString = body ? `\n${stringifyOpenAPI(body, null, 2)}` : '';
+
+            const httpRequest = `${method.toUpperCase()} ${decodeURI(path)} HTTP/1.1
+Host: ${host}
+${headerString}${bodyString}`;
+
+            return httpRequest;
+        },
+    },
 ];
 
 function indent(code: string, spaces: number) {
@@ -93,3 +135,25 @@ function indent(code: string, spaces: number) {
         .map((line) => (line ? indent + line : ''))
         .join('\n');
 }
+
+export function parseHostAndPath(url: string) {
+    try {
+        const urlObj = new URL(url);
+        const path = urlObj.pathname || '/';
+        return { host: urlObj.host, path };
+    } catch (e) {
+        // If the URL was invalid do our best to parse the URL.
+        // Check for the protocol part and pull it off to grab the host
+        const splitted = url.split('//');
+        const fullUrl = splitted[1] ? splitted[1] : url;
+
+        // separate paths from the first element (host)
+        const parts = fullUrl.split('/');
+        // pull off the host (mutates)
+        const host = parts.shift();
+        // add a leading slash and join the paths again
+        const path = '/' + parts.join('/');
+
+        return { host, path };
+    }
+}