@gitbook/react-openapi 1.0.2 → 1.0.4

package/src/OpenAPISchema.tsx

@@ -4,11 +4,11 @@ import { useId } from 'react';
 
 import { InteractiveSection } from './InteractiveSection';
 import { Markdown } from './Markdown';
+import { OpenAPIDisclosure } from './OpenAPIDisclosure';
+import { OpenAPISchemaName } from './OpenAPISchemaName';
+import { stringifyOpenAPI } from './stringifyOpenAPI';
 import type { OpenAPIClientContext } from './types';
 import { checkIsReference, resolveDescription } from './utils';
-import { stringifyOpenAPI } from './stringifyOpenAPI';
-import { OpenAPISchemaName } from './OpenAPISchemaName';
-import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 
 type CircularRefsIds = Map<OpenAPIV3.SchemaObject, string>;
 
@@ -27,7 +27,7 @@ export function OpenAPISchemaProperty(
         circularRefs?: CircularRefsIds;
         context: OpenAPIClientContext;
         className?: string;
-    },
+    }
 ) {
     const {
         schema,
@@ -47,12 +47,24 @@ export function OpenAPISchemaProperty(
         ? null
         : getSchemaAlternatives(schema, new Set(circularRefs.keys()));
 
+    if (alternatives?.[0]?.length) {
+        return (
+            <OpenAPISchemaAlternativesItem
+                {...props}
+                circularRefs={circularRefs}
+                context={context}
+                alternatives={alternatives}
+                parentCircularRef={parentCircularRef}
+            />
+        );
+    }
+
     if ((properties && properties.length > 0) || schema.type === 'object') {
         return (
             <InteractiveSection id={id} className={clsx('openapi-schema', className)}>
                 <OpenAPISchemaPresentation {...props} />
                 {properties && properties.length > 0 ? (
-                    <OpenAPIDisclosure context={context}>
+                    <OpenAPIDisclosure context={context} label={getDisclosureLabel(schema)}>
                         <OpenAPISchemaProperties
                             properties={properties}
                             circularRefs={circularRefs}
@@ -60,22 +72,9 @@ export function OpenAPISchemaProperty(
                         />
                     </OpenAPIDisclosure>
                 ) : null}
-            </InteractiveSection>
-        );
-    }
-
-    if (alternatives?.[0]?.length) {
-        return (
-            <InteractiveSection id={id} className={clsx('openapi-schema', className)}>
-                <OpenAPISchemaPresentation {...props} />
-                {alternatives[0].map((alternative, index) => (
-                    <OpenAPISchemaAlternative
-                        key={`alternative-${index}`}
-                        schema={alternative}
-                        circularRefs={circularRefs}
-                        context={context}
-                    />
-                ))}
+                {parentCircularRef ? (
+                    <OpenAPISchemaCircularRef id={parentCircularRef} schema={schema} />
+                ) : null}
             </InteractiveSection>
         );
     }
@@ -166,16 +165,72 @@ function OpenAPISchemaAlternative(props: {
     const { schema, circularRefs, context } = props;
     const id = useId();
     const subProperties = getSchemaProperties(schema);
+    const description = resolveDescription(schema);
+    const alternatives = getSchemaAlternatives(schema, new Set(circularRefs?.keys()));
+
+    if (alternatives?.[0]?.length && !subProperties?.length) {
+        return (
+            <>
+                {description ? (
+                    <Markdown source={description} className="openapi-schema-description" />
+                ) : null}
+                <OpenAPIDisclosure context={context} label={getDisclosureLabel(schema)}>
+                    <OpenAPISchemaAlternativesItem
+                        schema={schema}
+                        circularRefs={circularRefs}
+                        context={context}
+                        alternatives={alternatives}
+                    />
+                </OpenAPIDisclosure>
+            </>
+        );
+    }
 
     return (
-        <OpenAPIDisclosure context={context}>
-            <OpenAPISchemaProperties
-                id={id}
-                properties={subProperties ?? [{ schema }]}
-                circularRefs={subProperties ? new Map(circularRefs).set(schema, id) : circularRefs}
-                context={context}
-            />
-        </OpenAPIDisclosure>
+        <>
+            {description ? (
+                <Markdown source={description} className="openapi-schema-description" />
+            ) : null}
+            <OpenAPIDisclosure context={context} label={getDisclosureLabel(schema)}>
+                <OpenAPISchemaProperties
+                    id={id}
+                    properties={subProperties ?? [{ schema }]}
+                    circularRefs={
+                        subProperties ? new Map(circularRefs).set(schema, id) : circularRefs
+                    }
+                    context={context}
+                />
+            </OpenAPIDisclosure>
+        </>
+    );
+}
+
+function OpenAPISchemaAlternativesItem(
+    props: OpenAPISchemaPropertyEntry & {
+        circularRefs?: CircularRefsIds;
+        context: OpenAPIClientContext;
+        alternatives: OpenAPISchemaAlternatives;
+        parentCircularRef?: string;
+    }
+) {
+    const id = useId();
+    const { schema, circularRefs, context, alternatives, parentCircularRef } = props;
+
+    return (
+        <InteractiveSection id={id} className={clsx('openapi-schema')}>
+            <OpenAPISchemaPresentation {...props} />
+            {alternatives[0].map((alternative, index) => (
+                <OpenAPISchemaAlternative
+                    key={`alternative-${index}`}
+                    schema={alternative}
+                    circularRefs={circularRefs}
+                    context={context}
+                />
+            ))}
+            {parentCircularRef ? (
+                <OpenAPISchemaCircularRef id={parentCircularRef} schema={schema} />
+            ) : null}
+        </InteractiveSection>
     );
 }
 
@@ -219,7 +274,7 @@ export function OpenAPISchemaPresentation(props: OpenAPISchemaPropertyEntry) {
 
     const shouldDisplayExample = (schema: OpenAPIV3.SchemaObject): boolean => {
         return (
-            typeof schema.example === 'string' ||
+            (typeof schema.example === 'string' && !!schema.example) ||
             typeof schema.example === 'number' ||
             typeof schema.example === 'boolean' ||
             (Array.isArray(schema.example) && schema.example.length > 0) ||
@@ -234,10 +289,10 @@ export function OpenAPISchemaPresentation(props: OpenAPISchemaPropertyEntry) {
     return (
         <div className="openapi-schema-presentation">
             <OpenAPISchemaName
+                schema={schema}
                 type={getSchemaTitle(schema)}
                 propertyName={propertyName}
                 required={required}
-                deprecated={schema.deprecated}
             />
             {schema['x-deprecated-sunset'] ? (
                 <div className="openapi-deprecated-sunset openapi-schema-description openapi-markdown">
@@ -252,12 +307,7 @@ export function OpenAPISchemaPresentation(props: OpenAPISchemaPropertyEntry) {
             ) : null}
             {shouldDisplayExample(schema) ? (
                 <div className="openapi-schema-example">
-                    Example:{' '}
-                    <code>
-                        {typeof schema.example === 'string'
-                            ? schema.example
-                            : stringifyOpenAPI(schema.example)}
-                    </code>
+                    Example: <code>{formatExample(schema.example)}</code>
                 </div>
             ) : null}
             {schema.pattern ? (
@@ -276,17 +326,6 @@ export function OpenAPISchemaPresentation(props: OpenAPISchemaPropertyEntry) {
  * Get the sub-properties of a schema.
  */
 function getSchemaProperties(schema: OpenAPIV3.SchemaObject): null | OpenAPISchemaPropertyEntry[] {
-    if (schema.allOf) {
-        return schema.allOf.reduce((acc, subSchema) => {
-            const properties = getSchemaProperties(subSchema) ?? [
-                {
-                    schema: subSchema,
-                },
-            ];
-            return [...acc, ...properties];
-        }, [] as OpenAPISchemaPropertyEntry[]);
-    }
-
     // check array AND schema.items as this is sometimes null despite what the type indicates
     if (schema.type === 'array' && !!schema.items) {
         const items = schema.items;
@@ -295,6 +334,11 @@ function getSchemaProperties(schema: OpenAPIV3.SchemaObject): null | OpenAPISche
             return itemProperties;
         }
 
+        // If the items are a primitive type, we don't need to display them
+        if (['string', 'number', 'boolean', 'integer'].includes(items.type) && !items.enum) {
+            return null;
+        }
+
         return [
             {
                 propertyName: 'items',
@@ -333,13 +377,18 @@ function getSchemaProperties(schema: OpenAPIV3.SchemaObject): null | OpenAPISche
     return null;
 }
 
+type OpenAPISchemaAlternatives = [
+    OpenAPIV3.SchemaObject[],
+    OpenAPIV3.DiscriminatorObject | undefined,
+];
+
 /**
  * Get the alternatives to display for a schema.
  */
 export function getSchemaAlternatives(
     schema: OpenAPIV3.SchemaObject,
-    ancestors: Set<OpenAPIV3.SchemaObject> = new Set(),
-): null | [OpenAPIV3.SchemaObject[], OpenAPIV3.DiscriminatorObject | undefined] {
+    ancestors: Set<OpenAPIV3.SchemaObject> = new Set()
+): null | OpenAPISchemaAlternatives {
     const downAncestors = new Set(ancestors).add(schema);
 
     if (schema.anyOf) {
@@ -351,8 +400,7 @@ export function getSchemaAlternatives(
     }
 
     if (schema.allOf) {
-        // allOf is managed in `getSchemaProperties`
-        return null;
+        return [flattenAlternatives('allOf', schema.allOf, downAncestors), schema.discriminator];
     }
 
     return null;
@@ -361,14 +409,16 @@ export function getSchemaAlternatives(
 function flattenAlternatives(
     alternativeType: 'oneOf' | 'allOf' | 'anyOf',
     alternatives: OpenAPIV3.SchemaObject[],
-    ancestors: Set<OpenAPIV3.SchemaObject>,
+    ancestors: Set<OpenAPIV3.SchemaObject>
 ): OpenAPIV3.SchemaObject[] {
     return alternatives.reduce((acc, alternative) => {
         if (!!alternative[alternativeType] && !ancestors.has(alternative)) {
-            return [...acc, ...(getSchemaAlternatives(alternative, ancestors)?.[0] || [])];
+            acc.push(...(getSchemaAlternatives(alternative, ancestors)?.[0] || []));
+        } else {
+            acc.push(alternative);
         }
 
-        return [...acc, alternative];
+        return acc;
     }, [] as OpenAPIV3.SchemaObject[]);
 }
 
@@ -376,13 +426,8 @@ export function getSchemaTitle(
     schema: OpenAPIV3.SchemaObject,
 
     /** If the title is inferred in a oneOf with discriminator, we can use it to optimize the title */
-    discriminator?: OpenAPIV3.DiscriminatorObject,
+    discriminator?: OpenAPIV3.DiscriminatorObject
 ): string {
-    if (schema.title) {
-        // If the schema has a title, use it
-        return schema.title;
-    }
-
     // Try using the discriminator
     if (discriminator?.propertyName && schema.properties) {
         const discriminatorProperty = schema.properties[discriminator.propertyName];
@@ -409,7 +454,9 @@ export function getSchemaTitle(
         if (schema.format) {
             type += ` · ${schema.format}`;
         }
-    } else if ('anyOf' in schema) {
+    }
+
+    if ('anyOf' in schema) {
         type = 'any of';
     } else if ('oneOf' in schema) {
         type = 'one of';
@@ -419,21 +466,35 @@ export function getSchemaTitle(
         type = 'not';
     }
 
-    if (schema.minimum || schema.minLength) {
-        type += ` · min: ${schema.minimum || schema.minLength}`;
-    }
+    return type;
+}
 
-    if (schema.maximum || schema.maxLength) {
-        type += ` · max: ${schema.maximum || schema.maxLength}`;
-    }
+function getDisclosureLabel(schema: OpenAPIV3.SchemaObject): string | undefined {
+    if (schema.type === 'array' && !!schema.items) {
+        if (schema.items.oneOf) {
+            return 'available items';
+        }
 
-    if (schema.default) {
-        type += ` · default: ${schema.default}`;
+        // Fallback to "child attributes" for enums and objects
+        if (schema.items.enum || schema.items.type === 'object') {
+            return;
+        }
+
+        return schema.items.title ?? schema.title ?? getSchemaTitle(schema.items);
     }
 
-    if (schema.nullable) {
-        type = `${type} | nullable`;
+    return schema.title;
+}
+
+function formatExample(example: any): string {
+    if (typeof example === 'string') {
+        return example
+            .replace(/\n/g, ' ') // Replace newlines with spaces
+            .replace(/\s+/g, ' ') // Collapse multiple spaces/newlines into a single space
+            .replace(/([\{\}:,])\s+/g, '$1 ') // Ensure a space after {, }, :, and ,
+            .replace(/\s+([\{\}:,])/g, ' $1') // Ensure a space before {, }, :, and ,
+            .trim();
     }
 
-    return type;
+    return stringifyOpenAPI(example);
 }

package/src/OpenAPISchemaName.tsx

@@ -1,27 +1,60 @@
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import type React from 'react';
+
 interface OpenAPISchemaNameProps {
-    propertyName?: string | JSX.Element;
+    schema?: OpenAPIV3.SchemaObject;
+    propertyName?: string | React.JSX.Element;
     required?: boolean;
     type?: string;
-    deprecated?: boolean;
 }
 
 /**
  * Display the schema name row.
  * It includes the property name, type, required and deprecated status.
  */
-export function OpenAPISchemaName(props: OpenAPISchemaNameProps): JSX.Element {
-    const { type, propertyName, required, deprecated } = props;
+export function OpenAPISchemaName(props: OpenAPISchemaNameProps) {
+    const { schema, type, propertyName, required } = props;
+
+    const additionalItems = schema && getAdditionalItems(schema);
 
     return (
         <div className="openapi-schema-name">
             {propertyName ? (
-                <span data-deprecated={deprecated} className="openapi-schema-propertyname">
+                <span data-deprecated={schema?.deprecated} className="openapi-schema-propertyname">
                     {propertyName}
                 </span>
             ) : null}
-            {type ? <span className="openapi-schema-type">{type}</span> : null}
+            <span>
+                {type ? <span className="openapi-schema-type">{type}</span> : null}
+                {additionalItems ? (
+                    <span className="openapi-schema-type">{additionalItems}</span>
+                ) : null}
+            </span>
             {required ? <span className="openapi-schema-required">required</span> : null}
-            {deprecated ? <span className="openapi-deprecated">Deprecated</span> : null}
+            {schema?.deprecated ? <span className="openapi-deprecated">Deprecated</span> : null}
         </div>
     );
 }
+
+function getAdditionalItems(schema: OpenAPIV3.SchemaObject): string {
+    let additionalItems = '';
+
+    if (schema.minimum || schema.minLength) {
+        additionalItems += ` · min: ${schema.minimum || schema.minLength}`;
+    }
+
+    if (schema.maximum || schema.maxLength) {
+        additionalItems += ` · max: ${schema.maximum || schema.maxLength}`;
+    }
+
+    // If the schema has a default value, we display it
+    if (typeof schema.default !== 'undefined') {
+        additionalItems += ` · default: ${schema.default}`;
+    }
+
+    if (schema.nullable) {
+        additionalItems = ' | nullable';
+    }
+
+    return additionalItems;
+}

package/src/OpenAPISecurities.tsx

@@ -1,8 +1,8 @@
 import type { OpenAPIV3_1 } from '@gitbook/openapi-parser';
-import type { OpenAPIClientContext, OpenAPIOperationData } from './types';
 import { InteractiveSection } from './InteractiveSection';
 import { Markdown } from './Markdown';
 import { OpenAPISchemaName } from './OpenAPISchemaName';
+import type { OpenAPIClientContext, OpenAPIOperationData } from './types';
 import { resolveDescription } from './utils';
 
 /**
@@ -65,7 +65,7 @@ function getLabelForType(security: OpenAPIV3_1.SecuritySchemeObject) {
                 return <OpenAPISchemaName propertyName="Authorization" type="string" required />;
             }
 
-            if (security.scheme == 'bearer') {
+            if (security.scheme === 'bearer') {
                 const description = resolveDescription(security);
                 return (
                     <>
@@ -73,7 +73,7 @@ function getLabelForType(security: OpenAPIV3_1.SecuritySchemeObject) {
                         {/** Show a default description if none is provided */}
                         {!description ? (
                             <Markdown
-                                source={`Bearer authentication header of the form Bearer ${`&lt;token&gt;`}.`}
+                                source={`Bearer authentication header of the form Bearer ${'&lt;token&gt;'}.`}
                                 className="openapi-securities-description"
                             />
                         ) : null}

package/src/OpenAPITabs.tsx

@@ -1,12 +1,12 @@
 'use client';
 
 import { createContext, useContext, useEffect, useMemo, useState } from 'react';
-import { Key, Tab, TabList, TabPanel, Tabs, TabsProps } from 'react-aria-components';
+import { type Key, Tab, TabList, TabPanel, Tabs, type TabsProps } from 'react-aria-components';
+import { useIntersectionObserver } from 'usehooks-ts';
 import { Markdown } from './Markdown';
 import { useSyncedTabsGlobalState } from './useSyncedTabsGlobalState';
-import { useIntersectionObserver } from 'usehooks-ts';
 
-export type Tab = {
+export type TabItem = {
     key: Key;
     label: string;
     body: React.ReactNode;
@@ -14,8 +14,8 @@ export type Tab = {
 };
 
 type OpenAPITabsContextData = {
-    items: Tab[];
-    selectedTab: Tab;
+    items: TabItem[];
+    selectedTab: TabItem;
 };
 
 const OpenAPITabsContext = createContext<OpenAPITabsContextData | null>(null);
@@ -32,17 +32,16 @@ function useOpenAPITabsContext() {
  * The OpenAPI Tabs wrapper component.
  */
 export function OpenAPITabs(
-    props: React.PropsWithChildren<TabsProps & { items: Tab[]; stateKey?: string }>,
+    props: React.PropsWithChildren<TabsProps & { items: TabItem[]; 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 [ref, isIntersectionVisible] = useIntersectionObserver({
+        threshold: 0.1,
+        rootMargin: '200px',
+    });
+    const isVisible = stateKey ? isIntersectionVisible : true;
+    const defaultTab = items[0] as TabItem;
+    const [syncedTabs, setSyncedTabs] = useSyncedTabsGlobalState<TabItem>();
     const [selectedTabKey, setSelectedTabKey] = useState(() => {
         if (isVisible && stateKey && syncedTabs && syncedTabs.has(stateKey)) {
             const tabFromState = syncedTabs.get(stateKey);
@@ -50,7 +49,7 @@ export function OpenAPITabs(
         }
         return items[0]?.key;
     });
-    const [selectedTab, setSelectedTab] = useState<Tab>(defaultTab);
+    const [selectedTab, setSelectedTab] = useState<TabItem>(defaultTab);
 
     const handleSelectionChange = (key: Key) => {
         setSelectedTabKey(key);
@@ -74,11 +73,17 @@ export function OpenAPITabs(
             const tabFromState = syncedTabs.get(stateKey);
 
             if (!items.some((item) => item.key === tabFromState?.key)) {
-                return;
+                return setSelectedTab(defaultTab);
             }
 
             if (tabFromState && tabFromState?.key !== selectedTab?.key) {
-                setSelectedTab(tabFromState);
+                const tabFromItems = items.find((item) => item.key === tabFromState.key);
+
+                if (!tabFromItems) {
+                    return;
+                }
+
+                setSelectedTab(tabFromItems);
             }
         }
     }, [isVisible, stateKey, syncedTabs, selectedTabKey]);
@@ -88,6 +93,7 @@ export function OpenAPITabs(
     return (
         <OpenAPITabsContext.Provider value={contextValue}>
             <Tabs
+                ref={ref}
                 className="openapi-tabs"
                 onSelectionChange={handleSelectionChange}
                 selectedKey={selectedTab?.key}

package/src/ScalarApiButton.tsx

@@ -4,8 +4,8 @@ import { ApiClientModalProvider, useApiClientModal } from '@scalar/api-client-re
 import { useEffect, useImperativeHandle, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 
-import { useOpenAPIOperationContext } from './OpenAPIOperationContext';
 import { useEventCallback } from 'usehooks-ts';
+import { useOpenAPIOperationContext } from './OpenAPIOperationContext';
 
 /**
  * Button which launches the Scalar API Client
@@ -48,7 +48,7 @@ export function ScalarApiButton({
                         path={path}
                         specUrl={specUrl}
                     />,
-                    document.body,
+                    document.body
                 )}
         </div>
     );
@@ -88,7 +88,7 @@ function ScalarModalController(props: {
     useImperativeHandle(
         props.controllerRef,
         () => ({ openClient: openClient ? () => openClient() : undefined }),
-        [openClient],
+        [openClient]
     );
 
     // Open the client when the component is mounted.