@gitbook/react-openapi 1.0.0 → 1.0.2

package/dist/types.d.ts

@@ -4,6 +4,10 @@ export interface OpenAPIContextProps extends OpenAPIClientContext {
         code: string;
         syntax: string;
     }>;
+    renderHeading: (props: {
+        deprecated: boolean;
+        title: string;
+    }) => React.ReactNode;
     /** Spec url for the Scalar Api Client */
     specUrl: string;
 }

package/dist/useSyncedTabsGlobalState.d.ts

@@ -0,0 +1 @@
+export declare function useSyncedTabsGlobalState<T>(): readonly [Map<string, T>, (updater: (tabs: Map<string, T>) => Map<string, T>) => void];

package/dist/useSyncedTabsGlobalState.js

@@ -0,0 +1,16 @@
+'use client';
+import { create } from 'zustand';
+var useSyncedTabsStore = create()(function (set) { return ({
+    tabs: new Map(),
+    setTabs: function (updater) {
+        return set(function (state) { return ({
+            tabs: updater(new Map(state.tabs)), // Ensure a new Map is created for reactivity
+        }); });
+    },
+}); });
+// Selector for better performance - only re-renders when tabs change
+export function useSyncedTabsGlobalState() {
+    var tabs = useSyncedTabsStore(function (state) { return state.tabs; });
+    var setTabs = useSyncedTabsStore(function (state) { return state.setTabs; });
+    return [tabs, setTabs];
+}

package/dist/utils.d.ts

@@ -1,8 +1,31 @@
-import type { AnyObject, OpenAPIV3 } from '@gitbook/openapi-parser';
-export declare function noReference<T>(input: T | OpenAPIV3.ReferenceObject): T;
-export declare function checkIsReference(input: unknown): input is OpenAPIV3.ReferenceObject;
+import type { AnyObject, OpenAPIV3, OpenAPIV3_1 } from '@gitbook/openapi-parser';
+export declare function checkIsReference(input: unknown): input is OpenAPIV3.ReferenceObject | OpenAPIV3_1.ReferenceObject;
 export declare function createStateKey(key: string, scope?: string): string;
 /**
  * Resolve the description of an object.
  */
 export declare function resolveDescription(object: AnyObject): string | undefined;
+/**
+ * Extract descriptions from an object.
+ */
+export declare function extractDescriptions(object: AnyObject): {
+    description: any;
+    "x-gitbook-description-html": any;
+};
+/**
+ * Resolve the first example from an object.
+ */
+export declare function resolveFirstExample(object: AnyObject): any;
+/**
+ * Resolve the schema of a parameter.
+ * Extract the description, example and deprecated from parameter.
+ */
+export declare function resolveParameterSchema(parameter: OpenAPIV3.ParameterBaseObject): OpenAPIV3.SchemaObject;
+/**
+ * Transform a parameter object to a property object.
+ */
+export declare function parameterToProperty(parameter: OpenAPIV3.ParameterObject | OpenAPIV3.ReferenceObject | OpenAPIV3_1.ReferenceObject): {
+    propertyName: string | undefined;
+    schema: OpenAPIV3.SchemaObject;
+    required: boolean | undefined;
+};

package/dist/utils.js

@@ -1,9 +1,14 @@
-export function noReference(input) {
-    if (checkIsReference(input)) {
-        throw new Error('Reference found');
-    }
-    return input;
-}
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 export function checkIsReference(input) {
     return typeof input === 'object' && !!input && '$ref' in input;
 }
@@ -14,9 +19,67 @@ export function createStateKey(key, scope) {
  * Resolve the description of an object.
  */
 export function resolveDescription(object) {
-    return 'x-description-html' in object && typeof object['x-description-html'] === 'string'
-        ? object['x-description-html']
+    return 'x-gitbook-description-html' in object &&
+        typeof object['x-gitbook-description-html'] === 'string'
+        ? object['x-gitbook-description-html'].trim()
         : typeof object.description === 'string'
-            ? object.description
+            ? object.description.trim()
             : undefined;
 }
+/**
+ * Extract descriptions from an object.
+ */
+export function extractDescriptions(object) {
+    var _a;
+    return _a = {
+            description: object.description
+        },
+        _a['x-gitbook-description-html'] = 'x-gitbook-description-html' in object
+            ? object['x-gitbook-description-html']
+            : undefined,
+        _a;
+}
+/**
+ * Resolve the first example from an object.
+ */
+export function resolveFirstExample(object) {
+    if ('examples' in object && typeof object.examples === 'object' && object.examples) {
+        var keys = Object.keys(object.examples);
+        var firstKey = keys[0];
+        if (firstKey && object.examples[firstKey]) {
+            return object.examples[firstKey];
+        }
+    }
+    if ('example' in object && object.example !== undefined) {
+        return object.example;
+    }
+    return undefined;
+}
+/**
+ * Resolve the schema of a parameter.
+ * Extract the description, example and deprecated from parameter.
+ */
+export function resolveParameterSchema(parameter) {
+    var schema = checkIsReference(parameter.schema) ? undefined : parameter.schema;
+    return __assign(__assign(__assign({}, extractDescriptions(parameter)), { example: resolveFirstExample(parameter), 
+        // Deprecated can be defined at the parameter level
+        deprecated: parameter.deprecated }), schema);
+}
+/**
+ * Transform a parameter object to a property object.
+ */
+export function parameterToProperty(parameter) {
+    var _a;
+    if (checkIsReference(parameter)) {
+        return {
+            propertyName: (_a = parameter.$ref) !== null && _a !== void 0 ? _a : 'Unknown ref',
+            schema: {},
+            required: undefined,
+        };
+    }
+    return {
+        propertyName: parameter.name,
+        schema: resolveParameterSchema(parameter),
+        required: parameter.required,
+    };
+}

package/package.json

@@ -8,7 +8,7 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "1.0.0",
+    "version": "1.0.2",
     "sideEffects": false,
     "dependencies": {
         "@gitbook/openapi-parser": "workspace:*",
@@ -16,9 +16,11 @@
         "@scalar/oas-utils": "^0.2.101",
         "clsx": "^2.1.1",
         "flatted": "^3.2.9",
+        "json-xml-parse": "^1.3.0",
         "react-aria-components": "^1.6.0",
         "react-aria": "^3.37.0",
-        "usehooks-ts": "^3.1.0"
+        "usehooks-ts": "^3.1.0",
+        "zustand": "^5.0.3"
     },
     "devDependencies": {
         "bun-types": "^1.1.20",

package/src/InteractiveSection.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import clsx from 'clsx';
-import { useCallback, useRef, useState, useSyncExternalStore } from 'react';
+import { useRef, useState } from 'react';
 import { mergeProps, useButton, useDisclosure, useFocusRing } from 'react-aria';
 import { useDisclosureState } from 'react-stately';
 
@@ -11,30 +11,6 @@ interface InteractiveSectionTab {
     body: React.ReactNode;
 }
 
-let globalState: Record<string, string> = {};
-const listeners = new Set<() => void>();
-
-function useSyncedTabsGlobalState() {
-    const subscribe = useCallback((callback: () => void) => {
-        listeners.add(callback);
-        return () => listeners.delete(callback);
-    }, []);
-
-    const getSnapshot = useCallback(() => globalState, []);
-
-    const setSyncedTabs = useCallback(
-        (updater: (tabs: Record<string, string>) => Record<string, string>) => {
-            globalState = updater(globalState);
-            listeners.forEach((listener) => listener());
-        },
-        [],
-    );
-
-    const tabs = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
-
-    return [tabs, setSyncedTabs] as const;
-}
-
 /**
  * To optimize rendering, most of the components are server-components,
  * and the interactiveness is mainly handled by a few key components like this one.
@@ -59,8 +35,6 @@ export function InteractiveSection(props: {
     children?: React.ReactNode;
     /** Children to display within the container */
     overlay?: React.ReactNode;
-    /** An optional key referencing a value in global state */
-    stateKey?: string;
 }) {
     const {
         id,
@@ -73,16 +47,11 @@ export function InteractiveSection(props: {
         children,
         overlay,
         toggleIcon = '▶',
-        stateKey,
     } = props;
-    const [syncedTabs, setSyncedTabs] = useSyncedTabsGlobalState();
-    const tabFromState =
-        stateKey && stateKey in syncedTabs
-            ? tabs.find((tab) => tab.key === syncedTabs[stateKey])
-            : undefined;
-    const [selectedTabKey, setSelectedTab] = useState(tabFromState?.key ?? defaultTab);
+
+    const [selectedTabKey, setSelectedTab] = useState(defaultTab);
     const selectedTab: InteractiveSectionTab | undefined =
-        tabFromState ?? tabs.find((tab) => tab.key === selectedTabKey) ?? tabs[0];
+        tabs.find((tab) => tab.key === selectedTabKey) ?? tabs[0];
 
     const state = useDisclosureState({
         defaultExpanded: defaultOpened,
@@ -153,12 +122,6 @@ export function InteractiveSection(props: {
                                 value={selectedTab?.key ?? ''}
                                 onChange={(event) => {
                                     setSelectedTab(event.target.value);
-                                    if (stateKey) {
-                                        setSyncedTabs((state) => ({
-                                            ...state,
-                                            [stateKey]: event.target.value,
-                                        }));
-                                    }
                                     state.expand();
                                 }}
                             >

package/src/OpenAPICodeSample.tsx

@@ -3,9 +3,10 @@ import { generateMediaTypeExample, generateSchemaExample } from './generateSchem
 import { InteractiveSection } from './InteractiveSection';
 import { getServersURL } from './OpenAPIServerURL';
 import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
-import { noReference } from './utils';
+import { createStateKey } from './utils';
 import { stringifyOpenAPI } from './stringifyOpenAPI';
 import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
+import { checkIsReference } from './utils';
 
 /**
  * Display code samples to execute the operation.
@@ -20,24 +21,19 @@ export function OpenAPICodeSample(props: {
     const searchParams = new URLSearchParams();
     const headersObject: { [k: string]: string } = {};
 
-    data.operation.parameters?.forEach((rawParam) => {
-        const param = noReference(rawParam);
+    data.operation.parameters?.forEach((param) => {
         if (!param) {
             return;
         }
 
         if (param.in === 'header' && param.required) {
-            const example = param.schema
-                ? generateSchemaExample(noReference(param.schema))
-                : undefined;
+            const example = param.schema ? generateSchemaExample(param.schema) : undefined;
             if (example !== undefined && param.name) {
                 headersObject[param.name] =
                     typeof example !== 'string' ? stringifyOpenAPI(example) : example;
             }
         } else if (param.in === 'query' && param.required) {
-            const example = param.schema
-                ? generateSchemaExample(noReference(param.schema))
-                : undefined;
+            const example = param.schema ? generateSchemaExample(param.schema) : undefined;
             if (example !== undefined && param.name) {
                 searchParams.append(
                     param.name,
@@ -47,7 +43,9 @@ export function OpenAPICodeSample(props: {
         }
     });
 
-    const requestBody = noReference(data.operation.requestBody);
+    const requestBody = !checkIsReference(data.operation.requestBody)
+        ? data.operation.requestBody
+        : undefined;
     const requestBodyContentEntries = requestBody?.content
         ? Object.entries(requestBody.content)
         : undefined;
@@ -60,7 +58,9 @@ export function OpenAPICodeSample(props: {
             (searchParams.size ? `?${searchParams.toString()}` : ''),
         method: data.method,
         body: requestBodyContent
-            ? generateMediaTypeExample(requestBodyContent[1], { onlyRequired: true })
+            ? generateMediaTypeExample(requestBodyContent[1], {
+                  omitEmptyAndOptionalProperties: true,
+              })
             : undefined,
         headers: {
             ...getSecurityHeaders(data.securities),
@@ -115,7 +115,7 @@ export function OpenAPICodeSample(props: {
     }
 
     return (
-        <OpenAPITabs items={samples}>
+        <OpenAPITabs stateKey={createStateKey('codesample')} items={samples}>
             <InteractiveSection header={<OpenAPITabsList />} className="openapi-codesample">
                 <OpenAPITabsPanels />
             </InteractiveSection>

package/src/OpenAPIOperation.tsx

@@ -25,14 +25,17 @@ export function OpenAPIOperation(props: {
         blockKey: context.blockKey,
     };
 
-    const description = resolveDescription(operation)?.trim();
+    const description = resolveDescription(operation);
 
     return (
         <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>
+            <div className="openapi-summary">
+                {operation.summary
+                    ? context.renderHeading({
+                          deprecated: operation.deprecated ?? false,
+                          title: operation.summary,
+                      })
+                    : null}
                 {operation.deprecated && <div className="openapi-deprecated">Deprecated</div>}
             </div>
             <div className="openapi-columns">

package/src/OpenAPIRequestBody.tsx

@@ -1,18 +1,22 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import { OpenAPIRootSchema } from './OpenAPISchema';
-import { noReference } from './utils';
 import type { OpenAPIClientContext } from './types';
 import { InteractiveSection } from './InteractiveSection';
+import { checkIsReference } from './utils';
 
 /**
  * Display an interactive request body.
  */
 export function OpenAPIRequestBody(props: {
-    requestBody: OpenAPIV3.RequestBodyObject;
+    requestBody: OpenAPIV3.RequestBodyObject | OpenAPIV3.ReferenceObject;
     context: OpenAPIClientContext;
 }) {
     const { requestBody, context } = props;
 
+    if (checkIsReference(requestBody)) {
+        return null;
+    }
+
     return (
         <InteractiveSection
             header="Body"
@@ -24,7 +28,7 @@ export function OpenAPIRequestBody(props: {
                         label: contentType,
                         body: (
                             <OpenAPIRootSchema
-                                schema={noReference(mediaTypeObject.schema) ?? {}}
+                                schema={mediaTypeObject.schema ?? {}}
                                 context={context}
                             />
                         ),

package/src/OpenAPIResponse.tsx

@@ -1,6 +1,6 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import { OpenAPISchemaProperties } from './OpenAPISchema';
-import { checkIsReference, noReference, resolveDescription } from './utils';
+import { parameterToProperty, resolveDescription } from './utils';
 import type { OpenAPIClientContext } from './types';
 import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 
@@ -14,7 +14,7 @@ export function OpenAPIResponse(props: {
 }) {
     const { response, context, mediaType } = props;
     const headers = Object.entries(response.headers ?? {}).map(
-        ([name, header]) => [name, noReference(header) ?? {}] as const,
+        ([name, header]) => [name, header ?? {}] as const,
     );
     const content = Object.entries(mediaType.schema ?? {});
 
@@ -27,13 +27,11 @@ export function OpenAPIResponse(props: {
     return (
         <div className="openapi-response-body">
             {headers.length > 0 ? (
-                <OpenAPIDisclosure context={context} label={'Headers'}>
+                <OpenAPIDisclosure context={context} label="Headers">
                     <OpenAPISchemaProperties
-                        properties={headers.map(([name, header]) => ({
-                            propertyName: name,
-                            schema: noReference(header.schema) ?? {},
-                            required: header.required,
-                        }))}
+                        properties={headers.map(([name, header]) => {
+                            return parameterToProperty({ name, ...header });
+                        })}
                         context={context}
                     />
                 </OpenAPIDisclosure>
@@ -41,28 +39,10 @@ export function OpenAPIResponse(props: {
             <div className="openapi-responsebody">
                 <OpenAPISchemaProperties
                     id={`response-${context.blockKey}`}
-                    properties={[
-                        {
-                            schema: handleUnresolvedReference(mediaType.schema) ?? {},
-                        },
-                    ]}
+                    properties={mediaType.schema ? [{ schema: mediaType.schema }] : []}
                     context={context}
                 />
             </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;
-}