@gitbook/react-openapi 1.0.5 → 1.1.0

package/src/OpenAPISchema.tsx

@@ -1,18 +1,16 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
-import clsx from 'clsx';
 import { useId } from 'react';
 
-import { InteractiveSection } from './InteractiveSection';
+import clsx from 'clsx';
 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 { checkIsReference, resolveDescription, resolveFirstExample } from './utils';
 
 type CircularRefsIds = Map<OpenAPIV3.SchemaObject, string>;
 
-export interface OpenAPISchemaPropertyEntry {
+interface OpenAPISchemaPropertyEntry {
     propertyName?: string | undefined;
     required?: boolean | undefined;
     schema: OpenAPIV3.SchemaObject;
@@ -21,84 +19,60 @@ export interface OpenAPISchemaPropertyEntry {
 /**
  * Render a property of an OpenAPI schema.
  */
-export function OpenAPISchemaProperty(
-    props: OpenAPISchemaPropertyEntry & {
-        /** Set of objects already observed as parents */
-        circularRefs?: CircularRefsIds;
-        context: OpenAPIClientContext;
-        className?: string;
-    }
-) {
+function OpenAPISchemaProperty(props: {
+    property: OpenAPISchemaPropertyEntry;
+    context: OpenAPIClientContext;
+    circularRefs?: CircularRefsIds;
+    className?: string;
+}) {
     const {
-        schema,
+        property,
         circularRefs: parentCircularRefs = new Map<OpenAPIV3.SchemaObject, string>(),
         context,
         className,
     } = props;
 
-    const id = useId();
-
-    const parentCircularRef = parentCircularRefs.get(schema);
-    const circularRefs = new Map(parentCircularRefs).set(schema, id);
-
-    // Avoid recursing infinitely, and instead render a link to the parent schema
-    const properties = parentCircularRef ? null : getSchemaProperties(schema);
-    const alternatives = parentCircularRef
-        ? null
-        : getSchemaAlternatives(schema, new Set(circularRefs.keys()));
-
-    if (alternatives?.[0]?.length) {
-        return (
-            <OpenAPISchemaAlternativesItem
-                {...props}
-                circularRefs={circularRefs}
-                context={context}
-                alternatives={alternatives}
-                parentCircularRef={parentCircularRef}
-            />
-        );
-    }
+    const { schema } = property;
 
-    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} label={getDisclosureLabel(schema)}>
-                        <OpenAPISchemaProperties
-                            properties={properties}
-                            circularRefs={circularRefs}
-                            context={context}
-                        />
-                    </OpenAPIDisclosure>
-                ) : null}
-                {parentCircularRef ? (
-                    <OpenAPISchemaCircularRef id={parentCircularRef} schema={schema} />
-                ) : null}
-            </InteractiveSection>
-        );
-    }
+    const id = useId();
 
     return (
-        <InteractiveSection id={id} className={clsx('openapi-schema', className)}>
-            <OpenAPISchemaPresentation {...props} />
-            {(properties && properties.length > 0) ||
-            (schema.enum && schema.enum.length > 0) ||
-            parentCircularRef ? (
-                <>
-                    {properties?.length ? (
-                        <OpenAPISchemaProperties
-                            properties={properties}
-                            circularRefs={circularRefs}
-                            context={context}
-                        />
-                    ) : null}
-                    {parentCircularRef ? (
-                        <OpenAPISchemaCircularRef id={parentCircularRef} schema={schema} />
-                    ) : null}
-                </>
-            ) : null}
-        </InteractiveSection>
+        <div id={id} className={clsx('openapi-schema', className)}>
+            <OpenAPISchemaPresentation property={property} />
+            {(() => {
+                const parentCircularRef = parentCircularRefs.get(schema);
+
+                // Avoid recursing infinitely, and instead render a link to the parent schema
+                if (parentCircularRef) {
+                    return <OpenAPISchemaCircularRef id={parentCircularRef} schema={schema} />;
+                }
+
+                const circularRefs = parentCircularRefs.set(schema, id);
+                const properties = getSchemaProperties(schema);
+                const alternatives = getSchemaAlternatives(schema, new Set(circularRefs.keys()));
+                return (
+                    <>
+                        {alternatives?.map((schema, index) => (
+                            <OpenAPISchemaAlternative
+                                key={index}
+                                schema={schema}
+                                circularRefs={circularRefs}
+                                context={context}
+                            />
+                        ))}
+                        {properties?.length ? (
+                            <OpenAPIDisclosure context={context} label={getDisclosureLabel(schema)}>
+                                <OpenAPISchemaProperties
+                                    properties={properties}
+                                    circularRefs={circularRefs}
+                                    context={context}
+                                />
+                            </OpenAPIDisclosure>
+                        ) : null}
+                    </>
+                );
+            })()}
+        </div>
     );
 }
 
@@ -113,17 +87,13 @@ export function OpenAPISchemaProperties(props: {
 }) {
     const { id, properties, circularRefs, context } = props;
 
-    if (!properties.length) {
-        return null;
-    }
-
     return (
         <div id={id} className="openapi-schema-properties">
             {properties.map((property, index) => (
                 <OpenAPISchemaProperty
                     key={index}
                     circularRefs={circularRefs}
-                    {...property}
+                    property={property}
                     context={context}
                 />
             ))}
@@ -140,15 +110,18 @@ export function OpenAPIRootSchema(props: {
 }) {
     const { schema, context } = props;
 
-    // Avoid recursing infinitely, and instead render a link to the parent schema
     const properties = getSchemaProperties(schema);
 
-    if (properties && properties.length > 0) {
+    if (properties?.length) {
         return <OpenAPISchemaProperties properties={properties} context={context} />;
     }
 
     return (
-        <OpenAPISchemaProperty schema={schema} context={context} className="openapi-schema-root" />
+        <OpenAPISchemaProperty
+            className="openapi-schema-root"
+            property={{ schema }}
+            context={context}
+        />
     );
 }
 
@@ -159,32 +132,12 @@ export function OpenAPIRootSchema(props: {
  */
 function OpenAPISchemaAlternative(props: {
     schema: OpenAPIV3.SchemaObject;
-    circularRefs?: CircularRefsIds;
+    circularRefs: CircularRefsIds;
     context: OpenAPIClientContext;
 }) {
     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>
-            </>
-        );
-    }
+    const properties = getSchemaProperties(schema);
 
     return (
         <>
@@ -192,48 +145,24 @@ function OpenAPISchemaAlternative(props: {
                 <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}
-                />
+                {properties?.length ? (
+                    <OpenAPISchemaProperties
+                        properties={properties}
+                        circularRefs={circularRefs}
+                        context={context}
+                    />
+                ) : (
+                    <OpenAPISchemaProperty
+                        property={{ schema }}
+                        circularRefs={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>
-    );
-}
-
 /**
  * Render a circular reference to a schema.
  */
@@ -251,7 +180,7 @@ function OpenAPISchemaCircularRef(props: { id: string; schema: OpenAPIV3.SchemaO
 /**
  * Render the enum value for a schema.
  */
-export function OpenAPISchemaEnum(props: { enumValues: any[] }) {
+function OpenAPISchemaEnum(props: { enumValues: any[] }) {
     const { enumValues } = props;
 
     return (
@@ -269,22 +198,16 @@ export function OpenAPISchemaEnum(props: { enumValues: any[] }) {
     );
 }
 
-export function OpenAPISchemaPresentation(props: OpenAPISchemaPropertyEntry) {
-    const { schema, propertyName, required } = props;
-
-    const shouldDisplayExample = (schema: OpenAPIV3.SchemaObject): boolean => {
-        return (
-            (typeof schema.example === 'string' && !!schema.example) ||
-            typeof schema.example === 'number' ||
-            typeof schema.example === 'boolean' ||
-            (Array.isArray(schema.example) && schema.example.length > 0) ||
-            (typeof schema.example === 'object' &&
-                schema.example !== null &&
-                Object.keys(schema.example).length > 0)
-        );
-    };
+/**
+ * Render the top row of a schema. e.g: name, type, and required status.
+ */
+function OpenAPISchemaPresentation(props: { property: OpenAPISchemaPropertyEntry }) {
+    const {
+        property: { schema, propertyName, required },
+    } = props;
 
     const description = resolveDescription(schema);
+    const example = resolveFirstExample(schema);
 
     return (
         <div className="openapi-schema-presentation">
@@ -305,9 +228,9 @@ export function OpenAPISchemaPresentation(props: OpenAPISchemaPropertyEntry) {
             {description ? (
                 <Markdown source={description} className="openapi-schema-description" />
             ) : null}
-            {shouldDisplayExample(schema) ? (
+            {example ? (
                 <div className="openapi-schema-example">
-                    Example: <code>{formatExample(schema.example)}</code>
+                    Example: <code>{example}</code>
                 </div>
             ) : null}
             {schema.pattern ? (
@@ -327,7 +250,7 @@ export function OpenAPISchemaPresentation(props: OpenAPISchemaPropertyEntry) {
  */
 function getSchemaProperties(schema: OpenAPIV3.SchemaObject): null | OpenAPISchemaPropertyEntry[] {
     // check array AND schema.items as this is sometimes null despite what the type indicates
-    if (schema.type === 'array' && !!schema.items) {
+    if (schema.type === 'array' && schema.items && !checkIsReference(schema.items)) {
         const items = schema.items;
         const itemProperties = getSchemaProperties(items);
         if (itemProperties) {
@@ -335,16 +258,17 @@ function getSchemaProperties(schema: OpenAPIV3.SchemaObject): null | OpenAPISche
         }
 
         // If the items are a primitive type, we don't need to display them
-        if (['string', 'number', 'boolean', 'integer'].includes(items.type) && !items.enum) {
+        if (
+            (items.type === 'string' ||
+                items.type === 'number' ||
+                items.type === 'boolean' ||
+                items.type === 'integer') &&
+            !items.enum
+        ) {
             return null;
         }
 
-        return [
-            {
-                propertyName: 'items',
-                schema: items,
-            },
-        ];
+        return [{ propertyName: 'items', schema: items }];
     }
 
     if (schema.type === 'object' || schema.properties) {
@@ -352,6 +276,10 @@ function getSchemaProperties(schema: OpenAPIV3.SchemaObject): null | OpenAPISche
 
         if (schema.properties) {
             Object.entries(schema.properties).forEach(([propertyName, propertySchema]) => {
+                if (checkIsReference(propertySchema)) {
+                    return;
+                }
+
                 result.push({
                     propertyName,
                     required: Array.isArray(schema.required)
@@ -362,12 +290,10 @@ function getSchemaProperties(schema: OpenAPIV3.SchemaObject): null | OpenAPISche
             });
         }
 
-        if (schema.additionalProperties) {
-            const additionalProperties = schema.additionalProperties;
-
+        if (schema.additionalProperties && !checkIsReference(schema.additionalProperties)) {
             result.push({
                 propertyName: 'Other properties',
-                schema: additionalProperties === true ? {} : additionalProperties,
+                schema: schema.additionalProperties === true ? {} : schema.additionalProperties,
             });
         }
 
@@ -377,10 +303,7 @@ function getSchemaProperties(schema: OpenAPIV3.SchemaObject): null | OpenAPISche
     return null;
 }
 
-type OpenAPISchemaAlternatives = [
-    OpenAPIV3.SchemaObject[],
-    OpenAPIV3.DiscriminatorObject | undefined,
-];
+type AlternativeType = 'oneOf' | 'allOf' | 'anyOf';
 
 /**
  * Get the alternatives to display for a schema.
@@ -388,56 +311,57 @@ type OpenAPISchemaAlternatives = [
 export function getSchemaAlternatives(
     schema: OpenAPIV3.SchemaObject,
     ancestors: Set<OpenAPIV3.SchemaObject> = new Set()
-): null | OpenAPISchemaAlternatives {
-    const downAncestors = new Set(ancestors).add(schema);
+): OpenAPIV3.SchemaObject[] | null {
+    const alternatives:
+        | [AlternativeType, (OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject)[]]
+        | null = (() => {
+        if (schema.anyOf) {
+            return ['anyOf', schema.anyOf];
+        }
 
-    if (schema.anyOf) {
-        return [flattenAlternatives('anyOf', schema.anyOf, downAncestors), schema.discriminator];
-    }
+        if (schema.oneOf) {
+            return ['oneOf', schema.oneOf];
+        }
 
-    if (schema.oneOf) {
-        return [flattenAlternatives('oneOf', schema.oneOf, downAncestors), schema.discriminator];
-    }
+        if (schema.allOf) {
+            return ['allOf', schema.allOf];
+        }
+
+        return null;
+    })();
 
-    if (schema.allOf) {
-        return [flattenAlternatives('allOf', schema.allOf, downAncestors), schema.discriminator];
+    if (!alternatives) {
+        return null;
     }
 
-    return null;
+    const [type, schemas] = alternatives;
+    return flattenAlternatives(type, schemas, new Set(ancestors).add(schema));
 }
 
 function flattenAlternatives(
-    alternativeType: 'oneOf' | 'allOf' | 'anyOf',
-    alternatives: OpenAPIV3.SchemaObject[],
+    alternativeType: AlternativeType,
+    schemasOrRefs: (OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject)[],
     ancestors: Set<OpenAPIV3.SchemaObject>
 ): OpenAPIV3.SchemaObject[] {
-    return alternatives.reduce((acc, alternative) => {
-        if (!!alternative[alternativeType] && !ancestors.has(alternative)) {
-            acc.push(...(getSchemaAlternatives(alternative, ancestors)?.[0] || []));
-        } else {
-            acc.push(alternative);
+    return schemasOrRefs.reduce<OpenAPIV3.SchemaObject[]>((acc, schemaOrRef) => {
+        if (checkIsReference(schemaOrRef)) {
+            return acc;
         }
 
-        return acc;
-    }, [] as OpenAPIV3.SchemaObject[]);
-}
-
-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
-): string {
-    // Try using the discriminator
-    if (discriminator?.propertyName && schema.properties) {
-        const discriminatorProperty = schema.properties[discriminator.propertyName];
-        if (discriminatorProperty && !checkIsReference(discriminatorProperty)) {
-            if (discriminatorProperty.enum) {
-                return discriminatorProperty.enum.map((value) => value.toString()).join(' | ');
+        if (schemaOrRef[alternativeType] && !ancestors.has(schemaOrRef)) {
+            const schemas = getSchemaAlternatives(schemaOrRef, ancestors);
+            if (schemas) {
+                acc.push(...schemas);
             }
+            return acc;
         }
-    }
 
+        acc.push(schemaOrRef);
+        return acc;
+    }, []);
+}
+
+function getSchemaTitle(schema: OpenAPIV3.SchemaObject): string {
     // Otherwise try to infer a nice title
     let type = 'any';
 
@@ -469,7 +393,7 @@ export function getSchemaTitle(
     return type;
 }
 
-function getDisclosureLabel(schema: OpenAPIV3.SchemaObject): string | undefined {
+function getDisclosureLabel(schema: OpenAPIV3.SchemaObject): string {
     if (schema.type === 'array' && !!schema.items) {
         if (schema.items.oneOf) {
             return 'available items';
@@ -477,24 +401,11 @@ function getDisclosureLabel(schema: OpenAPIV3.SchemaObject): string | undefined
 
         // Fallback to "child attributes" for enums and objects
         if (schema.items.enum || schema.items.type === 'object') {
-            return;
+            return 'child attributes';
         }
 
         return schema.items.title ?? schema.title ?? getSchemaTitle(schema.items);
     }
 
-    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 stringifyOpenAPI(example);
+    return schema.title || 'child attributes';
 }

package/src/ScalarApiButton.tsx

@@ -1,24 +1,21 @@
 'use client';
 
 import { ApiClientModalProvider, useApiClientModal } from '@scalar/api-client-react';
-import { useEffect, useImperativeHandle, useRef, useState } from 'react';
+import { useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 
-import { useEventCallback } from 'usehooks-ts';
+import type { OpenAPIV3_1 } from '@gitbook/openapi-parser';
 import { useOpenAPIOperationContext } from './OpenAPIOperationContext';
 
 /**
  * Button which launches the Scalar API Client
  */
-export function ScalarApiButton({
-    method,
-    path,
-    specUrl,
-}: {
-    method: string;
+export function ScalarApiButton(props: {
+    method: OpenAPIV3_1.HttpMethods;
     path: string;
     specUrl: string;
 }) {
+    const { method, path, specUrl } = props;
     const [isOpen, setIsOpen] = useState(false);
     const controllerRef = useRef<ScalarModalControllerRef>(null);
     return (
@@ -55,21 +52,18 @@ export function ScalarApiButton({
 }
 
 function ScalarModal(props: {
-    method: string;
+    method: OpenAPIV3_1.HttpMethods;
     path: string;
     specUrl: string;
     controllerRef: React.Ref<ScalarModalControllerRef>;
 }) {
+    const { method, path, specUrl, controllerRef } = props;
     return (
         <ApiClientModalProvider
-            configuration={{ spec: { url: props.specUrl } }}
-            initialRequest={{ path: props.path, method: props.method }}
+            configuration={{ spec: { url: specUrl } }}
+            initialRequest={{ method, path }}
         >
-            <ScalarModalController
-                method={props.method}
-                path={props.path}
-                controllerRef={props.controllerRef}
-            />
+            <ScalarModalController method={method} path={path} controllerRef={controllerRef} />
         </ApiClientModalProvider>
     );
 }
@@ -79,28 +73,32 @@ type ScalarModalControllerRef = {
 };
 
 function ScalarModalController(props: {
-    method: string;
+    method: OpenAPIV3_1.HttpMethods;
     path: string;
     controllerRef: React.Ref<ScalarModalControllerRef>;
 }) {
+    const { method, path, controllerRef } = props;
     const client = useApiClientModal();
-    const openClient = client?.open;
+    const openScalarClient = client?.open;
+    const { onOpenClient: trackClientOpening } = useOpenAPIOperationContext();
+    const openClient = useMemo(() => {
+        if (openScalarClient) {
+            return () => {
+                openScalarClient({ method, path, _source: 'gitbook' });
+                trackClientOpening({ method, path });
+            };
+        }
+        return null;
+    }, [openScalarClient, method, path, trackClientOpening]);
     useImperativeHandle(
-        props.controllerRef,
+        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 });
-    });
+    // Open at mount
     useEffect(() => {
-        if (openClient) {
-            openClient();
-            trackOpening();
-        }
+        openClient?.();
     }, [openClient]);
     return null;
 }

package/src/dereference.ts

@@ -0,0 +1,29 @@
+import { type Filesystem, type OpenAPIV3xDocument, dereference } from '@gitbook/openapi-parser';
+
+const dereferenceCache = new WeakMap<Filesystem, Promise<OpenAPIV3xDocument>>();
+
+/**
+ * Memoized version of `dereferenceSchema`.
+ */
+export function dereferenceFilesystem(filesystem: Filesystem): Promise<OpenAPIV3xDocument> {
+    if (dereferenceCache.has(filesystem)) {
+        return dereferenceCache.get(filesystem) as Promise<OpenAPIV3xDocument>;
+    }
+
+    const promise = baseDereferenceFilesystem(filesystem);
+    dereferenceCache.set(filesystem, promise);
+    return promise;
+}
+
+/**
+ * Dereference an OpenAPI schema.
+ */
+async function baseDereferenceFilesystem(filesystem: Filesystem): Promise<OpenAPIV3xDocument> {
+    const result = await dereference(filesystem);
+
+    if (!result.schema) {
+        throw new Error('Failed to dereference OpenAPI document');
+    }
+
+    return result.schema as OpenAPIV3xDocument;
+}

package/src/index.ts

@@ -1,4 +1,5 @@
-export * from './resolveOpenAPIOperation';
+export * from './models';
 export * from './OpenAPIOperation';
 export * from './OpenAPIOperationContext';
-export type { OpenAPIOperationData } from './types';
+export * from './resolveOpenAPIOperation';
+export type { OpenAPIModelsData, OpenAPIOperationData } from './types';