@gitbook/react-openapi 0.7.0 → 1.0.0

package/src/OpenAPIDisclosureGroup.tsx

@@ -0,0 +1,136 @@
+interface Props {
+    groups: TDisclosureGroup[];
+    icon?: React.ReactNode;
+}
+
+type TDisclosureGroup = {
+    id: string;
+    label: string | React.ReactNode;
+    tabs?: {
+        id: string;
+        label: string | React.ReactNode;
+        body?: React.ReactNode;
+    }[];
+};
+
+import { mergeProps, useButton, useDisclosure, useFocusRing, useId } from 'react-aria';
+import {
+    DisclosureGroupProps,
+    DisclosureGroupState,
+    useDisclosureGroupState,
+    useDisclosureState,
+} from 'react-stately';
+import { createContext, useContext, useRef, useState } from 'react';
+
+const DisclosureGroupStateContext = createContext<DisclosureGroupState | null>(null);
+
+/**
+ * Display an interactive OpenAPI disclosure group.
+ */
+export function OpenAPIDisclosureGroup(props: DisclosureGroupProps & Props) {
+    const { icon, groups } = props;
+
+    const state = useDisclosureGroupState(props);
+
+    return (
+        <DisclosureGroupStateContext.Provider value={state}>
+            {groups.map((group) => (
+                <DisclosureItem icon={icon} key={group.id} group={group} />
+            ))}
+        </DisclosureGroupStateContext.Provider>
+    );
+}
+
+function DisclosureItem(props: { group: TDisclosureGroup; icon?: React.ReactNode }) {
+    const { icon, group } = props;
+
+    const defaultId = useId();
+    const id = group.id || defaultId;
+    const groupState = useContext(DisclosureGroupStateContext);
+    const isExpanded = groupState?.expandedKeys.has(id) || false;
+    const state = useDisclosureState({
+        isExpanded,
+        onExpandedChange() {
+            if (groupState) {
+                groupState.toggleKey(id);
+            }
+        },
+    });
+
+    const panelRef = useRef<HTMLDivElement | null>(null);
+    const triggerRef = useRef<HTMLButtonElement | null>(null);
+    const isDisabled = groupState?.isDisabled || !group.tabs?.length || false;
+    const { buttonProps: triggerProps, panelProps } = useDisclosure(
+        {
+            ...props,
+            isExpanded,
+            isDisabled,
+        },
+        state,
+        panelRef,
+    );
+    const { buttonProps } = useButton(triggerProps, triggerRef);
+    const { isFocusVisible, focusProps } = useFocusRing();
+
+    const defaultTab = group.tabs?.[0]?.id || '';
+    const [selectedTabKey, setSelectedTabKey] = useState(defaultTab);
+    const selectedTab = group.tabs?.find((tab) => tab.id === selectedTabKey);
+
+    return (
+        <div className="openapi-disclosure-group" aria-expanded={state.isExpanded}>
+            <div className="openapi-disclosure-group-header">
+                <button
+                    slot="trigger"
+                    ref={triggerRef}
+                    {...mergeProps(buttonProps, focusProps)}
+                    disabled={isDisabled}
+                    style={{
+                        outline: isFocusVisible
+                            ? '2px solid rgb(var(--primary-color-500)/0.4)'
+                            : 'none',
+                    }}
+                    className="openapi-disclosure-group-trigger"
+                >
+                    <div className="openapi-disclosure-group-icon">
+                        {icon || (
+                            <svg viewBox="0 0 24 24" className="openapi-disclosure-group-icon">
+                                <path d="m8.25 4.5 7.5 7.5-7.5 7.5" />
+                            </svg>
+                        )}
+                    </div>
+
+                    {group.label}
+                </button>
+                {group.tabs ? (
+                    <div className="openapi-disclosure-group-mediatype">
+                        {group.tabs?.length > 1 ? (
+                            <select
+                                className="openapi-section-select openapi-select openapi-disclosure-group-tabs-select"
+                                onClick={(event) => event.stopPropagation()}
+                                value={selectedTab?.id}
+                                onChange={(event) => {
+                                    setSelectedTabKey(event.target.value);
+                                    state.expand();
+                                }}
+                            >
+                                {group.tabs.map((tab) => (
+                                    <option key={tab.id} value={tab.id}>
+                                        {tab.label}
+                                    </option>
+                                ))}
+                            </select>
+                        ) : !!group.tabs[0] ? (
+                            <span>{group.tabs[0].label}</span>
+                        ) : null}
+                    </div>
+                ) : null}
+            </div>
+
+            {state.isExpanded && selectedTab && (
+                <div className="openapi-disclosure-group-panel" ref={panelRef} {...panelProps}>
+                    {selectedTab.body}
+                </div>
+            )}
+        </div>
+    );
+}

package/src/OpenAPIOperation.tsx

@@ -1,14 +1,12 @@
-import * as React from 'react';
-import classNames from 'classnames';
-import { ApiClientModalProvider } from '@scalar/api-client-react';
+import clsx from 'clsx';
 
-import { OpenAPIOperationData, toJSON } from './fetchOpenAPIOperation';
 import { Markdown } from './Markdown';
 import { OpenAPICodeSample } from './OpenAPICodeSample';
 import { OpenAPIResponseExample } from './OpenAPIResponseExample';
-import { OpenAPIServerURL } from './OpenAPIServerURL';
 import { OpenAPISpec } from './OpenAPISpec';
-import { OpenAPIClientContext, OpenAPIContextProps } from './types';
+import type { OpenAPIClientContext, OpenAPIContextProps, OpenAPIOperationData } from './types';
+import { OpenAPIPath } from './OpenAPIPath';
+import { resolveDescription } from './utils';
 
 /**
  * Display an interactive OpenAPI operation.
@@ -19,7 +17,7 @@ export function OpenAPIOperation(props: {
     context: OpenAPIContextProps;
 }) {
     const { className, data, context } = props;
-    const { operation, servers, method, path } = data;
+    const { operation } = data;
 
     const clientContext: OpenAPIClientContext = {
         defaultInteractiveOpened: context.defaultInteractiveOpened,
@@ -27,46 +25,42 @@ export function OpenAPIOperation(props: {
         blockKey: context.blockKey,
     };
 
+    const description = resolveDescription(operation)?.trim();
+
     return (
-        <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" id={context.id}>
-                        {operation.summary}
-                    </h2>
-                    {operation.description ? (
-                        <Markdown className="openapi-description" source={operation.description} />
+        <div className={clsx('openapi-operation', className)}>
+            <div className="openapi-summary" id={context.id}>
+                <h2 className="openapi-summary-title" data-deprecated={operation.deprecated}>
+                    {operation.summary}
+                </h2>
+                {operation.deprecated && <div className="openapi-deprecated">Deprecated</div>}
+            </div>
+            <div className="openapi-columns">
+                <div className="openapi-column-spec">
+                    {operation['x-deprecated-sunset'] ? (
+                        <div className="openapi-deprecated-sunset openapi-description openapi-markdown">
+                            This operation is deprecated and will be sunset on{' '}
+                            <span className="openapi-deprecated-sunset-date">
+                                {operation['x-deprecated-sunset']}
+                            </span>
+                            {`.`}
+                        </div>
                     ) : null}
-                    <div className="openapi-target">
-                        <span
-                            className={classNames(
-                                'openapi-method',
-                                `openapi-method-${method.toLowerCase()}`,
-                            )}
-                        >
-                            {method.toUpperCase()}
-                        </span>
-                        <span className="openapi-url">
-                            <OpenAPIServerURL servers={servers} />
-                            {path}
-                        </span>
-                    </div>
-                </div>
-                <div className={classNames('openapi-columns')}>
-                    <div className={classNames('openapi-column-spec')}>
-                        <OpenAPISpec rawData={toJSON(data)} context={clientContext} />
-                    </div>
-                    <div className={classNames('openapi-column-preview')}>
-                        <div className={classNames('openapi-column-preview-body')}>
-                            <OpenAPICodeSample {...props} />
-                            <OpenAPIResponseExample {...props} />
+                    {description ? (
+                        <div className="openapi-intro">
+                            <Markdown className="openapi-description" source={description} />
                         </div>
+                    ) : null}
+                    <OpenAPIPath data={data} context={context} />
+                    <OpenAPISpec data={data} context={clientContext} />
+                </div>
+                <div className="openapi-column-preview">
+                    <div className="openapi-column-preview-body">
+                        <OpenAPICodeSample {...props} />
+                        <OpenAPIResponseExample {...props} />
                     </div>
                 </div>
             </div>
-        </ApiClientModalProvider>
+        </div>
     );
 }

package/src/OpenAPIOperationContext.tsx

@@ -0,0 +1,45 @@
+'use client';
+
+import { createContext, useContext, useMemo } from 'react';
+import { useEventCallback } from 'usehooks-ts';
+
+interface OpenAPIOperationPointer {
+    path: string;
+    method: string;
+}
+
+interface OpenAPIOperationContextValue {
+    onOpenClient: (pointer: OpenAPIOperationPointer) => void;
+}
+
+const OpenAPIOperationContext = createContext<OpenAPIOperationContextValue>({
+    onOpenClient: () => {},
+});
+
+/**
+ * Provider for the OpenAPIOperationContext.
+ */
+export function OpenAPIOperationContextProvider(
+    props: React.PropsWithChildren<Partial<OpenAPIOperationContextValue>>,
+) {
+    const { children } = props;
+
+    const onOpenClient = useEventCallback((pointer: OpenAPIOperationPointer) => {
+        props.onOpenClient?.(pointer);
+    });
+
+    const value = useMemo(() => ({ onOpenClient }), [onOpenClient]);
+
+    return (
+        <OpenAPIOperationContext.Provider value={value}>
+            {children}
+        </OpenAPIOperationContext.Provider>
+    );
+}
+
+/**
+ * Hook to access the OpenAPIOperationContext.
+ */
+export function useOpenAPIOperationContext() {
+    return useContext(OpenAPIOperationContext);
+}

package/src/OpenAPIPath.tsx

@@ -0,0 +1,65 @@
+import { ScalarApiButton } from './ScalarApiButton';
+import type { OpenAPIOperationData, OpenAPIContextProps } from './types';
+
+/**
+ * Display the path of an operation.
+ */
+export function OpenAPIPath(props: {
+    data: OpenAPIOperationData;
+    context: OpenAPIContextProps;
+}): JSX.Element {
+    const { data, context } = props;
+    const { method, path } = data;
+    const { specUrl } = context;
+
+    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>
+            {data['x-hideTryItPanel'] || data.operation['x-hideTryItPanel'] ? null : (
+                <ScalarApiButton method={method} path={path} specUrl={specUrl} />
+            )}
+        </div>
+    );
+}
+
+// Format the path to highlight placeholders
+function formatPath(path: string) {
+    // Matches placeholders like {id}, {userId}, etc.
+    const regex = /\{(\w+)\}/g;
+
+    const parts: (string | 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>);
+        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 === '/') {
+                return [
+                    ...acc,
+                    <span className="openapi-path-separator" key={`sep-${index}`}>
+                        /
+                    </span>,
+                    part,
+                ];
+            }
+            return [...acc, part];
+        },
+        [] as (string | JSX.Element)[],
+    );
+
+    return <span>{formattedPath}</span>;
+}

package/src/OpenAPIRequestBody.tsx

@@ -1,11 +1,8 @@
-import * as React from 'react';
-
-import { OpenAPIV3 } from 'openapi-types';
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import { OpenAPIRootSchema } from './OpenAPISchema';
 import { noReference } from './utils';
-import { OpenAPIClientContext } from './types';
+import type { OpenAPIClientContext } from './types';
 import { InteractiveSection } from './InteractiveSection';
-import { Markdown } from './Markdown';
 
 /**
  * Display an interactive request body.
@@ -34,14 +31,6 @@ export function OpenAPIRequestBody(props: {
                     };
                 },
             )}
-            defaultOpened={context.defaultInteractiveOpened}
-        >
-            {requestBody.description ? (
-                <Markdown
-                    source={requestBody.description}
-                    className="openapi-requestbody-description"
-                />
-            ) : null}
-        </InteractiveSection>
+        />
     );
 }

package/src/OpenAPIResponse.tsx

@@ -1,44 +1,33 @@
-import * as React from 'react';
-import classNames from 'classnames';
-import { OpenAPIV3 } from 'openapi-types';
-import { OpenAPIRootSchema, OpenAPISchemaProperties } from './OpenAPISchema';
-import { noReference } from './utils';
-import { OpenAPIClientContext } from './types';
-import { InteractiveSection } from './InteractiveSection';
-import { Markdown } from './Markdown';
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import { OpenAPISchemaProperties } from './OpenAPISchema';
+import { checkIsReference, noReference, resolveDescription } from './utils';
+import type { OpenAPIClientContext } from './types';
+import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 
 /**
  * Display an interactive response body.
  */
 export function OpenAPIResponse(props: {
     response: OpenAPIV3.ResponseObject;
+    mediaType: OpenAPIV3.MediaTypeObject;
     context: OpenAPIClientContext;
 }) {
-    const { response, context } = props;
-    const content = Object.entries(response.content ?? {});
+    const { response, context, mediaType } = props;
     const headers = Object.entries(response.headers ?? {}).map(
         ([name, header]) => [name, noReference(header) ?? {}] as const,
     );
+    const content = Object.entries(mediaType.schema ?? {});
 
-    if (content.length === 0 && !response.description && headers.length === 0) {
+    const description = resolveDescription(response);
+
+    if (content.length === 0 && !description && headers.length === 0) {
         return null;
     }
 
     return (
-        <>
-            {response.description ? (
-                <Markdown source={response.description} className="openapi-response-description" />
-            ) : null}
-
+        <div className="openapi-response-body">
             {headers.length > 0 ? (
-                <InteractiveSection
-                    toggeable
-                    defaultOpened={!!context.defaultInteractiveOpened}
-                    toggleCloseIcon={context.icons.chevronDown}
-                    toggleOpenIcon={context.icons.chevronRight}
-                    header="Headers"
-                    className={classNames('openapi-responseheaders')}
-                >
+                <OpenAPIDisclosure context={context} label={'Headers'}>
                     <OpenAPISchemaProperties
                         properties={headers.map(([name, header]) => ({
                             propertyName: name,
@@ -47,26 +36,33 @@ export function OpenAPIResponse(props: {
                         }))}
                         context={context}
                     />
-                </InteractiveSection>
+                </OpenAPIDisclosure>
             ) : null}
-            {content.length > 0 ? (
-                <InteractiveSection
-                    header="Body"
-                    className={classNames('openapi-responsebody')}
-                    tabs={content.map(([contentType, mediaType]) => {
-                        return {
-                            key: contentType,
-                            label: contentType,
-                            body: (
-                                <OpenAPIRootSchema
-                                    schema={noReference(mediaType.schema) ?? {}}
-                                    context={context}
-                                />
-                            ),
-                        };
-                    })}
+            <div className="openapi-responsebody">
+                <OpenAPISchemaProperties
+                    id={`response-${context.blockKey}`}
+                    properties={[
+                        {
+                            schema: handleUnresolvedReference(mediaType.schema) ?? {},
+                        },
+                    ]}
+                    context={context}
                 />
-            ) : null}
-        </>
+            </div>
+        </div>
     );
 }
+
+function handleUnresolvedReference(
+    input: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined,
+): OpenAPIV3.SchemaObject {
+    const isReference = checkIsReference(input);
+
+    if (isReference || input === undefined) {
+        // If we find a reference that wasn't resolved or needed to be resolved externally, do not try to render it.
+        // Instead we render `any`
+        return {};
+    }
+
+    return input;
+}

package/src/OpenAPIResponseExample.tsx

@@ -1,9 +1,10 @@
-import * as React from 'react';
-import { InteractiveSection } from './InteractiveSection';
-import { OpenAPIOperationData } from './fetchOpenAPIOperation';
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import { generateSchemaExample } from './generateSchemaExample';
-import { OpenAPIContextProps } from './types';
-import { createStateKey, noReference } from './utils';
+import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
+import { checkIsReference, noReference, resolveDescription } from './utils';
+import { stringifyOpenAPI } from './stringifyOpenAPI';
+import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
+import { InteractiveSection } from './InteractiveSection';
 
 /**
  * Display an example of the response content.
@@ -38,50 +39,107 @@ export function OpenAPIResponseExample(props: {
     });
 
     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,
-            );
+        .map(([key, value]) => {
+            const responseObject = noReference(value);
+            const mediaTypeObject = (() => {
+                if (!responseObject.content) {
+                    return null;
+                }
+                const key = Object.keys(responseObject.content)[0];
+                return (
+                    responseObject.content['application/json'] ??
+                    (key ? responseObject.content[key] : null)
+                );
+            })();
 
-            if (!schema) {
-                return null;
+            if (!mediaTypeObject) {
+                return {
+                    key: key,
+                    label: key,
+                    description: resolveDescription(responseObject),
+                    body: <OpenAPIEmptyResponseExample />,
+                };
             }
 
-            const example = generateSchemaExample(schema);
-            if (example === undefined) {
-                return null;
-            }
+            const example = handleUnresolvedReference(
+                (() => {
+                    const { examples, example } = mediaTypeObject;
+                    if (examples) {
+                        const key = Object.keys(examples)[0];
+                        if (key) {
+                            // @TODO handle multiple examples
+                            const firstExample = noReference(examples[key]);
+                            if (firstExample) {
+                                return firstExample;
+                            }
+                        }
+                    }
+
+                    if (example) {
+                        return { value: example };
+                    }
+
+                    const schema = noReference(mediaTypeObject.schema);
+                    if (!schema) {
+                        return null;
+                    }
+
+                    return { value: generateSchemaExample(schema) };
+                })(),
+            );
 
             return {
-                key: `${response[0]}`,
-                label: `${response[0]}`,
-                body: (
+                key: key,
+                label: key,
+                description: resolveDescription(responseObject),
+                body: example?.value ? (
                     <context.CodeBlock
                         code={
-                            typeof example === 'string' ? example : JSON.stringify(example, null, 2)
+                            typeof example.value === 'string'
+                                ? example.value
+                                : stringifyOpenAPI(example.value, null, 2)
                         }
                         syntax="json"
                     />
+                ) : (
+                    <OpenAPIEmptyResponseExample />
                 ),
             };
         })
-        .filter((val): val is { key: string; label: string; body: any } => Boolean(val));
+        .filter((val): val is { key: string; label: string; body: any; description: string } =>
+            Boolean(val),
+        );
 
     if (examples.length === 0) {
         return null;
     }
 
     return (
-        <InteractiveSection
-            stateKey={createStateKey('response', context.blockKey)}
-            header="Response"
-            className="openapi-response-example"
-            tabs={examples}
-        />
+        <OpenAPITabs items={examples}>
+            <InteractiveSection header={<OpenAPITabsList />} className="openapi-response-example">
+                <OpenAPITabsPanels />
+            </InteractiveSection>
+        </OpenAPITabs>
     );
 }
+
+function OpenAPIEmptyResponseExample() {
+    return (
+        <pre className="openapi-response-example-empty">
+            <p>No body</p>
+        </pre>
+    );
+}
+
+function handleUnresolvedReference(
+    input: OpenAPIV3.ExampleObject | null,
+): OpenAPIV3.ExampleObject | null {
+    const isReference = checkIsReference(input?.value);
+
+    if (isReference) {
+        // If we find a reference that wasn't resolved or needed to be resolved externally, render out the URL
+        return { value: input.value.$ref };
+    }
+
+    return input;
+}