@gitbook/react-openapi 0.7.0 → 1.0.0

package/dist/types.d.ts

@@ -1,6 +1,4 @@
-export type IconComponent = React.ComponentType<{
-    className?: string;
-}>;
+import type { OpenAPICustomOperationProperties, OpenAPICustomSpecProperties, OpenAPIV3 } from '@gitbook/openapi-parser';
 export interface OpenAPIContextProps extends OpenAPIClientContext {
     CodeBlock: React.ComponentType<{
         code: string;
@@ -13,6 +11,7 @@ export interface OpenAPIClientContext {
     icons: {
         chevronDown: React.ReactNode;
         chevronRight: React.ReactNode;
+        plus: React.ReactNode;
     };
     /**
      * Force all sections to be opened by default.
@@ -26,13 +25,13 @@ export interface OpenAPIClientContext {
     /** Optional id attached to the OpenAPI Operation heading and used as an anchor */
     id?: string;
 }
-export interface OpenAPIFetcher {
-    /**
-     * Fetch an OpenAPI file by its URL. It should return a fully parsed OpenAPI v3 document.
-     */
-    fetch: (url: string) => Promise<any>;
-    /**
-     * Parse markdown to the react element to render.
-     */
-    parseMarkdown?: (input: string) => Promise<string>;
+export interface OpenAPIOperationData extends OpenAPICustomSpecProperties {
+    path: string;
+    method: string;
+    /** Servers to be used for this operation */
+    servers: OpenAPIV3.ServerObject[];
+    /** Spec of the operation */
+    operation: OpenAPIV3.OperationObject<OpenAPICustomOperationProperties>;
+    /** Securities that should be used for this operation */
+    securities: [string, OpenAPIV3.SecuritySchemeObject][];
 }

package/dist/utils.d.ts

@@ -1,3 +1,8 @@
-import { OpenAPIV3 } from 'openapi-types';
+import type { AnyObject, OpenAPIV3 } from '@gitbook/openapi-parser';
 export declare function noReference<T>(input: T | OpenAPIV3.ReferenceObject): T;
+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.
+ */
+export declare function resolveDescription(object: AnyObject): string | undefined;

package/dist/utils.js

@@ -1,9 +1,22 @@
 export function noReference(input) {
-    if (typeof input === 'object' && !!input && '$ref' in input) {
+    if (checkIsReference(input)) {
         throw new Error('Reference found');
     }
     return input;
 }
+export function checkIsReference(input) {
+    return typeof input === 'object' && !!input && '$ref' in input;
+}
 export function createStateKey(key, scope) {
-    return scope ? `${scope}_${key}` : key;
+    return scope ? "".concat(scope, "_").concat(key) : key;
+}
+/**
+ * Resolve the description of an object.
+ */
+export function resolveDescription(object) {
+    return 'x-description-html' in object && typeof object['x-description-html'] === 'string'
+        ? object['x-description-html']
+        : typeof object.description === 'string'
+            ? object.description
+            : undefined;
 }

package/package.json

@@ -8,29 +8,30 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "0.7.0",
+    "version": "1.0.0",
+    "sideEffects": false,
     "dependencies": {
-        "@scalar/api-client-react": "1.0.65",
-        "classnames": "^2.5.1",
+        "@gitbook/openapi-parser": "workspace:*",
+        "@scalar/api-client-react": "1.0.87",
+        "@scalar/oas-utils": "^0.2.101",
+        "clsx": "^2.1.1",
         "flatted": "^3.2.9",
-        "openapi-types": "^12.1.3",
-        "swagger2openapi": "^7.0.8",
-        "yaml": "1.10.2"
+        "react-aria-components": "^1.6.0",
+        "react-aria": "^3.37.0",
+        "usehooks-ts": "^3.1.0"
     },
     "devDependencies": {
-        "@types/swagger2openapi": "^7.0.4",
         "bun-types": "^1.1.20",
         "typescript": "^5.5.3"
     },
     "peerDependencies": {
-        "react": "*",
-        "recoil": "^0.7.7"
+        "react": "*"
     },
     "scripts": {
-        "build": "tsc",
+        "build": "tsc --project tsconfig.build.json",
         "typecheck": "tsc --noEmit",
         "unit": "bun test",
-        "dev": "tsc -w",
+        "dev": "bun run build -- --watch",
         "clean": "rm -rf ./dist"
     },
     "files": [

package/src/InteractiveSection.tsx

@@ -1,8 +1,9 @@
 'use client';
 
-import classNames from 'classnames';
-import React from 'react';
-import { atom, useRecoilState } from 'recoil';
+import clsx from 'clsx';
+import { useCallback, useRef, useState, useSyncExternalStore } from 'react';
+import { mergeProps, useButton, useDisclosure, useFocusRing } from 'react-aria';
+import { useDisclosureState } from 'react-stately';
 
 interface InteractiveSectionTab {
     key: string;
@@ -10,10 +11,29 @@ interface InteractiveSectionTab {
     body: React.ReactNode;
 }
 
-const syncedTabsAtom = atom<Record<string, string>>({
-    key: 'syncedTabState',
-    default: {},
-});
+let globalState: Record<string, string> = {};
+const listeners = new Set<() => void>();
+
+function useSyncedTabsGlobalState() {
+    const subscribe = useCallback((callback: () => void) => {
+        listeners.add(callback);
+        return () => listeners.delete(callback);
+    }, []);
+
+    const getSnapshot = useCallback(() => globalState, []);
+
+    const setSyncedTabs = useCallback(
+        (updater: (tabs: Record<string, string>) => Record<string, string>) => {
+            globalState = updater(globalState);
+            listeners.forEach((listener) => listener());
+        },
+        [],
+    );
+
+    const tabs = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+    return [tabs, setSyncedTabs] as const;
+}
 
 /**
  * To optimize rendering, most of the components are server-components,
@@ -27,15 +47,14 @@ export function InteractiveSection(props: {
     toggeable?: boolean;
     /** Default state of the toggle */
     defaultOpened?: boolean;
-    /** Icons to display for the toggle */
-    toggleOpenIcon?: React.ReactNode;
-    toggleCloseIcon?: React.ReactNode;
+    /** Icon to display for the toggle */
+    toggleIcon?: React.ReactNode;
     /** Tabs of content to display */
     tabs?: Array<InteractiveSectionTab>;
     /** Default tab to have opened */
     defaultTab?: string;
     /** Content of the header */
-    header: React.ReactNode;
+    header?: React.ReactNode;
     /** Body of the section */
     children?: React.ReactNode;
     /** Children to display within the container */
@@ -53,99 +72,121 @@ export function InteractiveSection(props: {
         header,
         children,
         overlay,
-        toggleOpenIcon = '▶',
-        toggleCloseIcon = '▼',
+        toggleIcon = '▶',
         stateKey,
     } = props;
-    const [syncedTabs, setSyncedTabs] = useRecoilState(syncedTabsAtom);
+    const [syncedTabs, setSyncedTabs] = useSyncedTabsGlobalState();
     const tabFromState =
         stateKey && stateKey in syncedTabs
             ? tabs.find((tab) => tab.key === syncedTabs[stateKey])
             : undefined;
-
-    const [opened, setOpened] = React.useState(defaultOpened);
-    const [selectedTabKey, setSelectedTab] = React.useState(tabFromState?.key ?? defaultTab);
+    const [selectedTabKey, setSelectedTab] = useState(tabFromState?.key ?? defaultTab);
     const selectedTab: InteractiveSectionTab | undefined =
         tabFromState ?? tabs.find((tab) => tab.key === selectedTabKey) ?? tabs[0];
 
+    const state = useDisclosureState({
+        defaultExpanded: defaultOpened,
+    });
+    const panelRef = useRef<HTMLDivElement | null>(null);
+    const triggerRef = useRef<HTMLButtonElement | null>(null);
+    const { buttonProps: triggerProps, panelProps } = useDisclosure({}, state, panelRef);
+    const { buttonProps } = useButton(triggerProps, triggerRef);
+    const { isFocusVisible, focusProps } = useFocusRing();
+
     return (
         <div
             id={id}
-            className={classNames(
+            className={clsx(
                 'openapi-section',
                 toggeable ? 'openapi-section-toggeable' : null,
                 className,
-                toggeable ? `${className}-${opened ? 'opened' : 'closed'}` : null,
+                toggeable ? `${className}-${state.isExpanded ? 'opened' : 'closed'}` : null,
             )}
         >
-            <div
-                onClick={() => {
-                    if (toggeable) {
-                        setOpened(!opened);
-                    }
-                }}
-                className={classNames('openapi-section-header', `${className}-header`)}
-            >
+            {header ? (
                 <div
-                    className={classNames(
-                        'openapi-section-header-content',
-                        `${className}-header-content`,
-                    )}
+                    onClick={() => {
+                        if (toggeable) {
+                            state.toggle();
+                        }
+                    }}
+                    className={clsx('openapi-section-header', `${className}-header`)}
                 >
-                    {header}
+                    <div
+                        className={clsx(
+                            'openapi-section-header-content',
+                            `${className}-header-content`,
+                        )}
+                    >
+                        {(children || selectedTab?.body) && toggeable ? (
+                            <button
+                                {...mergeProps(buttonProps, focusProps)}
+                                ref={triggerRef}
+                                className={clsx('openapi-section-toggle', `${className}-toggle`)}
+                                style={{
+                                    outline: isFocusVisible
+                                        ? '2px solid rgb(var(--primary-color-500) / 0.4)'
+                                        : 'none',
+                                }}
+                            >
+                                {toggleIcon}
+                            </button>
+                        ) : null}
+                        {header}
+                    </div>
+                    <div
+                        className={clsx(
+                            'openapi-section-header-controls',
+                            `${className}-header-controls`,
+                        )}
+                        onClick={(event) => {
+                            event.stopPropagation();
+                        }}
+                    >
+                        {tabs.length > 1 ? (
+                            <select
+                                className={clsx(
+                                    '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,
+                                        }));
+                                    }
+                                    state.expand();
+                                }}
+                            >
+                                {tabs.map((tab) => (
+                                    <option key={tab.key} value={tab.key}>
+                                        {tab.label}
+                                    </option>
+                                ))}
+                            </select>
+                        ) : null}
+                    </div>
                 </div>
+            ) : null}
+            {(!toggeable || state.isExpanded) && (children || selectedTab?.body) ? (
                 <div
-                    className={classNames(
-                        'openapi-section-header-controls',
-                        `${className}-header-controls`,
-                    )}
-                    onClick={(event) => {
-                        event.stopPropagation();
-                    }}
+                    ref={panelRef}
+                    {...panelProps}
+                    className={clsx('openapi-section-body', `${className}-body`)}
                 >
-                    {tabs.length ? (
-                        <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) => (
-                                <option key={tab.key} value={tab.key}>
-                                    {tab.label}
-                                </option>
-                            ))}
-                        </select>
-                    ) : null}
-                    {(children || selectedTab?.body) && toggeable ? (
-                        <button
-                            className={classNames('openapi-section-toggle', `${className}-toggle`)}
-                            onClick={() => setOpened(!opened)}
-                        >
-                            {opened ? toggleCloseIcon : toggleOpenIcon}
-                        </button>
-                    ) : null}
-                </div>
-            </div>
-            {(!toggeable || opened) && (children || selectedTab?.body) ? (
-                <div className={classNames('openapi-section-body', `${className}-body`)}>
                     {children}
                     {selectedTab?.body}
                 </div>
             ) : null}
-            {overlay}
+            {overlay ? (
+                <div className={clsx('openapi-section-overlay', `${className}-overlay`)}>
+                    {overlay}
+                </div>
+            ) : null}
         </div>
     );
 }

package/src/Markdown.tsx

@@ -1,12 +1,11 @@
-import * as React from 'react';
-import classNames from 'classnames';
+import clsx from 'clsx';
 
 export function Markdown(props: { source: string; className?: string }) {
     const { source, className } = props;
 
     return (
         <div
-            className={classNames('openapi-markdown', className)}
+            className={clsx('openapi-markdown', className)}
             dangerouslySetInnerHTML={{ __html: source }}
         />
     );

package/src/OpenAPICodeSample.tsx

@@ -1,13 +1,11 @@
-import * as React from 'react';
-
 import { CodeSampleInput, codeSampleGenerators } from './code-samples';
-import { OpenAPIOperationData } from './fetchOpenAPIOperation';
 import { generateMediaTypeExample, generateSchemaExample } from './generateSchemaExample';
 import { InteractiveSection } from './InteractiveSection';
 import { getServersURL } from './OpenAPIServerURL';
-import { ScalarApiButton } from './ScalarApiButton';
-import { OpenAPIContextProps } from './types';
+import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
 import { noReference } from './utils';
+import { stringifyOpenAPI } from './stringifyOpenAPI';
+import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
 
 /**
  * Display code samples to execute the operation.
@@ -32,15 +30,15 @@ export function OpenAPICodeSample(props: {
             const example = param.schema
                 ? generateSchemaExample(noReference(param.schema))
                 : undefined;
-            if (example !== undefined) {
+            if (example !== undefined && param.name) {
                 headersObject[param.name] =
-                    typeof example !== 'string' ? JSON.stringify(example) : example;
+                    typeof example !== 'string' ? stringifyOpenAPI(example) : example;
             }
         } else if (param.in === 'query' && param.required) {
             const example = param.schema
                 ? generateSchemaExample(noReference(param.schema))
                 : undefined;
-            if (example !== undefined) {
+            if (example !== undefined && param.name) {
                 searchParams.append(
                     param.name,
                     String(Array.isArray(example) ? example[0] : example),
@@ -50,7 +48,10 @@ export function OpenAPICodeSample(props: {
     });
 
     const requestBody = noReference(data.operation.requestBody);
-    const requestBodyContent = requestBody ? Object.entries(requestBody.content)[0] : undefined;
+    const requestBodyContentEntries = requestBody?.content
+        ? Object.entries(requestBody.content)
+        : undefined;
+    const requestBodyContent = requestBodyContentEntries?.[0];
 
     const input: CodeSampleInput = {
         url:
@@ -108,21 +109,17 @@ export function OpenAPICodeSample(props: {
     const codeSamplesDisabled =
         data['x-codeSamples'] === false || data.operation['x-codeSamples'] === false;
     const samples = customCodeSamples ?? (!codeSamplesDisabled ? autoCodeSamples : []);
+
     if (samples.length === 0) {
         return null;
     }
 
     return (
-        <InteractiveSection
-            header="Request"
-            className="openapi-codesample"
-            tabs={samples}
-            overlay={
-                data['x-hideTryItPanel'] || data.operation['x-hideTryItPanel'] ? null : (
-                    <ScalarApiButton />
-                )
-            }
-        />
+        <OpenAPITabs items={samples}>
+            <InteractiveSection header={<OpenAPITabsList />} className="openapi-codesample">
+                <OpenAPITabsPanels />
+            </InteractiveSection>
+        </OpenAPITabs>
     );
 }
 
@@ -130,6 +127,7 @@ function getSecurityHeaders(securities: OpenAPIOperationData['securities']): {
     [key: string]: string;
 } {
     const security = securities[0];
+
     if (!security) {
         return {};
     }
@@ -137,12 +135,28 @@ function getSecurityHeaders(securities: OpenAPIOperationData['securities']): {
     switch (security[1].type) {
         case 'http': {
             let scheme = security[1].scheme;
-            if (scheme === 'bearer') {
+            let format = security[1].bearerFormat ?? 'YOUR_SECRET_TOKEN';
+
+            if (scheme?.includes('bearer')) {
                 scheme = 'Bearer';
+            } else if (scheme?.includes('basic')) {
+                scheme = 'Basic';
+                format = 'username:password';
+            } else if (scheme?.includes('token')) {
+                scheme = 'Token';
             }
 
             return {
-                Authorization: scheme + ' ' + (security[1].bearerFormat ?? '<token>'),
+                Authorization: scheme + ' ' + format,
+            };
+        }
+        case 'apiKey': {
+            if (security[1].in !== 'header') return {};
+
+            const name = security[1].name ?? 'Authorization';
+
+            return {
+                [name]: 'YOUR_API_KEY',
             };
         }
         default: {

package/src/OpenAPIDisclosure.tsx

@@ -0,0 +1,50 @@
+import { useRef } from 'react';
+import type { OpenAPIClientContext } from './types';
+import { mergeProps, useButton, useDisclosure, useFocusRing } from 'react-aria';
+import { useDisclosureState } from 'react-stately';
+
+interface Props {
+    context: OpenAPIClientContext;
+    children: React.ReactNode;
+    label?: string;
+}
+
+/**
+ * Display an interactive OpenAPI disclosure.
+ * The label is optional and defaults to "child attributes".
+ */
+export function OpenAPIDisclosure({ context, children, label }: Props): JSX.Element {
+    const state = useDisclosureState({});
+    const panelRef = useRef<HTMLDivElement | null>(null);
+    const triggerRef = useRef<HTMLButtonElement | null>(null);
+    const { buttonProps: triggerProps, panelProps } = useDisclosure({}, state, panelRef);
+    const { buttonProps } = useButton(triggerProps, triggerRef);
+    const { isFocusVisible, focusProps } = useFocusRing();
+
+    return (
+        <div className="openapi-disclosure">
+            <button
+                ref={triggerRef}
+                {...mergeProps(buttonProps, focusProps)}
+                slot="trigger"
+                className="openapi-disclosure-trigger"
+                style={{
+                    outline: isFocusVisible
+                        ? '2px solid rgb(var(--primary-color-500) / 0.4)'
+                        : 'none',
+                }}
+            >
+                {context.icons.plus}
+                <span>
+                    {`${state.isExpanded ? 'Hide' : 'Show'} ${label ? label : `child attributes`}`}
+                </span>
+            </button>
+
+            {state.isExpanded && (
+                <div ref={panelRef} {...panelProps} className="openapi-disclosure-panel">
+                    {children}
+                </div>
+            )}
+        </div>
+    );
+}