@gitbook/react-openapi 1.0.2 → 1.0.3

package/dist/types.d.ts

@@ -1,13 +1,25 @@
 import type { OpenAPICustomOperationProperties, OpenAPICustomSpecProperties, OpenAPIV3 } from '@gitbook/openapi-parser';
 export interface OpenAPIContextProps extends OpenAPIClientContext {
-    CodeBlock: React.ComponentType<{
+    /**
+     * Render a code block.
+     */
+    renderCodeBlock: (props: {
         code: string;
         syntax: string;
-    }>;
+    }) => React.ReactNode;
+    /**
+     * Render the heading of the operation.
+     */
     renderHeading: (props: {
         deprecated: boolean;
         title: string;
     }) => React.ReactNode;
+    /**
+     * Render the document of the operation.
+     */
+    renderDocument: (props: {
+        document: object;
+    }) => React.ReactNode;
     /** Spec url for the Scalar Api Client */
     specUrl: string;
 }

package/dist/util/server.d.ts

@@ -0,0 +1,9 @@
+import { OpenAPIV3 } from '@gitbook/openapi-parser';
+/**
+ * Get the default URL for the server.
+ */
+export declare function getDefaultServerURL(servers: OpenAPIV3.ServerObject[]): string;
+/**
+ * Interpolate the server URL with the default values of the variables.
+ */
+export declare function interpolateServerURL(server: OpenAPIV3.ServerObject): string;

package/dist/{OpenAPIServerURL.jsx → util/server.js}

@@ -1,40 +1,19 @@
-import { OpenAPIServerURLVariable } from './OpenAPIServerURLVariable';
 /**
- * Show the url of the server with variables replaced by their default values.
+ * Get the default URL for the server.
  */
-export function OpenAPIServerURL(props) {
-    var _a;
-    var servers = props.servers;
+export function getDefaultServerURL(servers) {
     var server = servers[0];
     if (!server) {
-        return null;
+        // Return empty string if no server is found to display nothing
+        return '';
     }
-    var parts = parseServerURL((_a = server === null || server === void 0 ? void 0 : server.url) !== null && _a !== void 0 ? _a : '');
-    return (<span>
-            {parts.map(function (part, i) {
-            var _a;
-            if (part.kind === 'text') {
-                return <span key={i}>{part.text}</span>;
-            }
-            else {
-                var variable = (_a = server.variables) === null || _a === void 0 ? void 0 : _a[part.name];
-                if (!variable) {
-                    return <span key={i}>{"{".concat(part.name, "}")}</span>;
-                }
-                return (<OpenAPIServerURLVariable key={i} name={part.name} variable={variable}/>);
-            }
-        })}
-        </span>);
+    return interpolateServerURL(server);
 }
 /**
- * Get the default URL for the server.
+ * Interpolate the server URL with the default values of the variables.
  */
-export function getServersURL(servers) {
+export function interpolateServerURL(server) {
     var _a;
-    var server = servers[0];
-    if (!server) {
-        return '';
-    }
     var parts = parseServerURL((_a = server === null || server === void 0 ? void 0 : server.url) !== null && _a !== void 0 ? _a : '');
     return parts
         .map(function (part) {

package/dist/utils.d.ts

@@ -4,7 +4,7 @@ export declare function createStateKey(key: string, scope?: string): string;
 /**
  * Resolve the description of an object.
  */
-export declare function resolveDescription(object: AnyObject): string | undefined;
+export declare function resolveDescription(object: OpenAPIV3.SchemaObject | AnyObject): string | undefined;
 /**
  * Extract descriptions from an object.
  */

package/dist/utils.js

@@ -19,6 +19,9 @@ export function createStateKey(key, scope) {
  * Resolve the description of an object.
  */
 export function resolveDescription(object) {
+    if ('items' in object && object.items) {
+        return resolveDescription(object.items);
+    }
     return 'x-gitbook-description-html' in object &&
         typeof object['x-gitbook-description-html'] === 'string'
         ? object['x-gitbook-description-html'].trim()

package/package.json

@@ -8,7 +8,7 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "1.0.2",
+    "version": "1.0.3",
     "sideEffects": false,
     "dependencies": {
         "@gitbook/openapi-parser": "workspace:*",
@@ -30,7 +30,7 @@
         "react": "*"
     },
     "scripts": {
-        "build": "tsc --project tsconfig.build.json",
+        "build": "rm -rf ./dist && tsc --project tsconfig.build.json",
         "typecheck": "tsc --noEmit",
         "unit": "bun test",
         "dev": "bun run build -- --watch",

package/src/OpenAPICodeSample.tsx

@@ -1,12 +1,12 @@
 import { CodeSampleInput, codeSampleGenerators } from './code-samples';
 import { generateMediaTypeExample, generateSchemaExample } from './generateSchemaExample';
 import { InteractiveSection } from './InteractiveSection';
-import { getServersURL } from './OpenAPIServerURL';
 import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
 import { createStateKey } from './utils';
 import { stringifyOpenAPI } from './stringifyOpenAPI';
 import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
 import { checkIsReference } from './utils';
+import { getDefaultServerURL } from './util/server';
 
 /**
  * Display code samples to execute the operation.
@@ -53,15 +53,11 @@ export function OpenAPICodeSample(props: {
 
     const input: CodeSampleInput = {
         url:
-            getServersURL(data.servers) +
+            getDefaultServerURL(data.servers) +
             data.path +
             (searchParams.size ? `?${searchParams.toString()}` : ''),
         method: data.method,
-        body: requestBodyContent
-            ? generateMediaTypeExample(requestBodyContent[1], {
-                  omitEmptyAndOptionalProperties: true,
-              })
-            : undefined,
+        body: requestBodyContent ? generateMediaTypeExample(requestBodyContent[1]) : undefined,
         headers: {
             ...getSecurityHeaders(data.securities),
             ...headersObject,
@@ -76,7 +72,10 @@ export function OpenAPICodeSample(props: {
     const autoCodeSamples = codeSampleGenerators.map((generator) => ({
         key: `default-${generator.id}`,
         label: generator.label,
-        body: <context.CodeBlock code={generator.generate(input)} syntax={generator.syntax} />,
+        body: context.renderCodeBlock({
+            code: generator.generate(input),
+            syntax: generator.syntax,
+        }),
     }));
 
     // Use custom samples if defined
@@ -99,7 +98,10 @@ export function OpenAPICodeSample(props: {
                 .map((sample) => ({
                     key: `redocly-${sample.lang}`,
                     label: sample.label,
-                    body: <context.CodeBlock code={sample.source} syntax={sample.lang} />,
+                    body: context.renderCodeBlock({
+                        code: sample.source,
+                        syntax: sample.lang,
+                    }),
                 }));
         }
     });

package/src/OpenAPIOperation.tsx

@@ -7,6 +7,7 @@ import { OpenAPISpec } from './OpenAPISpec';
 import type { OpenAPIClientContext, OpenAPIContextProps, OpenAPIOperationData } from './types';
 import { OpenAPIPath } from './OpenAPIPath';
 import { resolveDescription } from './utils';
+import { OpenAPICustomOperationProperties, OpenAPIV3 } from '@gitbook/openapi-parser';
 
 /**
  * Display an interactive OpenAPI operation.
@@ -25,11 +26,9 @@ export function OpenAPIOperation(props: {
         blockKey: context.blockKey,
     };
 
-    const description = resolveDescription(operation);
-
     return (
         <div className={clsx('openapi-operation', className)}>
-            <div className="openapi-summary">
+            <div className="openapi-summary" id={operation.summary ? undefined : context.id}>
                 {operation.summary
                     ? context.renderHeading({
                           deprecated: operation.deprecated ?? false,
@@ -49,11 +48,7 @@ export function OpenAPIOperation(props: {
                             {`.`}
                         </div>
                     ) : null}
-                    {description ? (
-                        <div className="openapi-intro">
-                            <Markdown className="openapi-description" source={description} />
-                        </div>
-                    ) : null}
+                    <OpenAPIOperationDescription operation={operation} context={context} />
                     <OpenAPIPath data={data} context={context} />
                     <OpenAPISpec data={data} context={clientContext} />
                 </div>
@@ -67,3 +62,30 @@ export function OpenAPIOperation(props: {
         </div>
     );
 }
+
+function OpenAPIOperationDescription(props: {
+    operation: OpenAPIV3.OperationObject<OpenAPICustomOperationProperties>;
+    context: OpenAPIContextProps;
+}) {
+    const { operation } = props;
+    if (operation['x-gitbook-description-document']) {
+        return (
+            <div className="openapi-intro">
+                {props.context.renderDocument({
+                    document: operation['x-gitbook-description-document'],
+                })}
+            </div>
+        );
+    }
+
+    const description = resolveDescription(operation);
+    if (!description) {
+        return null;
+    }
+
+    return (
+        <div className="openapi-intro">
+            <Markdown className="openapi-description" source={description} />
+        </div>
+    );
+}

package/src/OpenAPIResponseExample.tsx

@@ -5,6 +5,7 @@ import { checkIsReference, createStateKey, resolveDescription } from './utils';
 import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
 import { InteractiveSection } from './InteractiveSection';
 import { json2xml } from './json2xml';
+import { stringifyOpenAPI } from './stringifyOpenAPI';
 
 /**
  * Display an example of the response content.
@@ -208,7 +209,7 @@ function OpenAPIExample(props: {
         return <OpenAPIEmptyResponseExample />;
     }
 
-    return <context.CodeBlock code={code} syntax={syntax} />;
+    return context.renderCodeBlock({ code, syntax });
 }
 
 function stringifyExample(args: { example: OpenAPIV3.ExampleObject; xml: boolean }): string | null {
@@ -226,7 +227,7 @@ function stringifyExample(args: { example: OpenAPIV3.ExampleObject; xml: boolean
         return json2xml(example.value);
     }
 
-    return JSON.stringify(example.value, null, 2);
+    return stringifyOpenAPI(example.value, null, 2);
 }
 
 /**

package/src/OpenAPISchema.tsx

@@ -47,23 +47,6 @@ export function OpenAPISchemaProperty(
         ? null
         : getSchemaAlternatives(schema, new Set(circularRefs.keys()));
 
-    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}>
-                        <OpenAPISchemaProperties
-                            properties={properties}
-                            circularRefs={circularRefs}
-                            context={context}
-                        />
-                    </OpenAPIDisclosure>
-                ) : null}
-            </InteractiveSection>
-        );
-    }
-
     if (alternatives?.[0]?.length) {
         return (
             <InteractiveSection id={id} className={clsx('openapi-schema', className)}>
@@ -76,6 +59,29 @@ export function OpenAPISchemaProperty(
                         context={context}
                     />
                 ))}
+                {parentCircularRef ? (
+                    <OpenAPISchemaCircularRef id={parentCircularRef} schema={schema} />
+                ) : null}
+            </InteractiveSection>
+        );
+    }
+
+    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>
         );
     }
@@ -166,16 +172,24 @@ function OpenAPISchemaAlternative(props: {
     const { schema, circularRefs, context } = props;
     const id = useId();
     const subProperties = getSchemaProperties(schema);
+    const description = resolveDescription(schema);
 
     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>
+        </>
     );
 }
 
@@ -219,7 +233,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 +248,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 +266,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 +285,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 +293,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',
@@ -351,8 +354,7 @@ export function getSchemaAlternatives(
     }
 
     if (schema.allOf) {
-        // allOf is managed in `getSchemaProperties`
-        return null;
+        return [flattenAlternatives('allOf', schema.allOf, downAncestors), schema.discriminator];
     }
 
     return null;
@@ -378,11 +380,6 @@ export function getSchemaTitle(
     /** If the title is inferred in a oneOf with discriminator, we can use it to optimize the title */
     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];
@@ -419,21 +416,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';
+        }
+
+        // Fallback to "child attributes" for enums and objects
+        if (schema.items.enum || schema.items.type === 'object') {
+            return;
+        }
 
-    if (schema.default) {
-        type += ` · default: ${schema.default}`;
+        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,8 +1,10 @@
+import { OpenAPIV3 } from '@gitbook/openapi-parser';
+
 interface OpenAPISchemaNameProps {
+    schema?: OpenAPIV3.SchemaObject;
     propertyName?: string | JSX.Element;
     required?: boolean;
     type?: string;
-    deprecated?: boolean;
 }
 
 /**
@@ -10,18 +12,48 @@ interface OpenAPISchemaNameProps {
  * It includes the property name, type, required and deprecated status.
  */
 export function OpenAPISchemaName(props: OpenAPISchemaNameProps): JSX.Element {
-    const { type, propertyName, required, deprecated } = props;
+    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/OpenAPITabs.tsx

@@ -74,11 +74,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]);