@gitbook/react-openapi 1.1.10 → 1.2.0

package/dist/types.d.ts

@@ -1,54 +1,4 @@
 import type { OpenAPICustomOperationProperties, OpenAPICustomSpecProperties, OpenAPIV3 } from '@gitbook/openapi-parser';
-export interface OpenAPIClientContext {
-    /**
-     * Icons used in the block.
-     */
-    icons: {
-        chevronDown: React.ReactNode;
-        chevronRight: React.ReactNode;
-        plus: React.ReactNode;
-    };
-    /**
-     * Force all sections to be opened by default.
-     * @default false
-     */
-    defaultInteractiveOpened?: boolean;
-    /**
-     * The key of the block
-     */
-    blockKey?: string;
-    /**
-     * Optional id attached to the heading and used as an anchor.
-     */
-    id?: string;
-}
-export interface OpenAPIContext extends OpenAPIClientContext {
-    /**
-     * Render a code block.
-     */
-    renderCodeBlock: (props: {
-        code: string;
-        syntax: string;
-    }) => React.ReactNode;
-    /**
-     * Render the heading of the operation.
-     */
-    renderHeading: (props: {
-        deprecated?: boolean;
-        title: string;
-        stability?: string;
-    }) => React.ReactNode;
-    /**
-     * Render the document of the operation.
-     */
-    renderDocument: (props: {
-        document: object;
-    }) => React.ReactNode;
-    /**
-     * Specification URL.
-     */
-    specUrl: string;
-}
 export type OpenAPISecurityWithRequired = OpenAPIV3.SecuritySchemeObject & {
     required?: boolean;
 };
@@ -62,3 +12,11 @@ export interface OpenAPIOperationData extends OpenAPICustomSpecProperties {
     /** Securities that should be used for this operation */
     securities: [string, OpenAPISecurityWithRequired][];
 }
+export interface OpenAPIWebhookData extends OpenAPICustomSpecProperties {
+    name: string;
+    method: string;
+    /** Servers to be used for this operation */
+    servers: OpenAPIV3.ServerObject[];
+    /** Spec of the webhook */
+    operation: OpenAPIV3.OperationObject<OpenAPICustomOperationProperties>;
+}

package/dist/util/example.d.ts

@@ -0,0 +1,35 @@
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import type { OpenAPIContext } from '../context';
+/**
+ * Generate an example from a reference object.
+ */
+export declare function getExampleFromReference(ref: OpenAPIV3.ReferenceObject, context: OpenAPIContext): OpenAPIV3.ExampleObject;
+/**
+ * Get examples from a media type object.
+ */
+export declare function getExamplesFromMediaTypeObject(args: {
+    mediaType: string;
+    mediaTypeObject: OpenAPIV3.MediaTypeObject;
+    context: OpenAPIContext;
+}): {
+    key: string;
+    example: OpenAPIV3.ExampleObject;
+}[];
+/**
+ * Get example from a schema object.
+ */
+export declare function getExampleFromSchema(args: {
+    schema: OpenAPIV3.SchemaObject;
+}): OpenAPIV3.ExampleObject;
+/**
+ * Get the examples from a media type object.
+ */
+export declare function getExamples(props: {
+    mediaTypeObject: OpenAPIV3.MediaTypeObject;
+    mediaType: string;
+    context: OpenAPIContext;
+}): {
+    key: string;
+    label: string;
+    body: import("react").JSX.Element;
+}[];

package/dist/util/example.jsx

@@ -0,0 +1,103 @@
+import { OpenAPIExample } from '../OpenAPIExample';
+import { generateSchemaExample } from '../generateSchemaExample';
+import { tString } from '../translate';
+import { checkIsReference } from '../utils';
+/**
+ * Generate an example from a reference object.
+ */
+export function getExampleFromReference(ref, context) {
+    return {
+        summary: tString(context.translation, 'unresolved_reference'),
+        value: { $ref: ref.$ref },
+    };
+}
+/**
+ * Get examples from a media type object.
+ */
+export function getExamplesFromMediaTypeObject(args) {
+    var _a;
+    var _b, _c;
+    var mediaTypeObject = args.mediaTypeObject, mediaType = args.mediaType, context = args.context;
+    if (mediaTypeObject.examples) {
+        return Object.entries(mediaTypeObject.examples).map(function (_a) {
+            var key = _a[0], example = _a[1];
+            return {
+                key: key,
+                example: checkIsReference(example)
+                    ? getExampleFromReference(example, context)
+                    : example,
+            };
+        });
+    }
+    if (mediaTypeObject.example) {
+        return [{ key: 'default', example: { value: mediaTypeObject.example } }];
+    }
+    if (mediaTypeObject.schema) {
+        if (mediaType === 'application/xml') {
+            // @TODO normally we should use the name of the schema but we don't have it
+            // fix it when we got the reference name
+            var root = (_c = (_b = mediaTypeObject.schema.xml) === null || _b === void 0 ? void 0 : _b.name) !== null && _c !== void 0 ? _c : 'object';
+            return [
+                {
+                    key: 'default',
+                    example: {
+                        value: (_a = {},
+                            _a[root] = generateSchemaExample(mediaTypeObject.schema, {
+                                xml: mediaType === 'application/xml',
+                                mode: 'read',
+                            }),
+                            _a),
+                    },
+                },
+            ];
+        }
+        return [
+            {
+                key: 'default',
+                example: {
+                    value: generateSchemaExample(mediaTypeObject.schema, {
+                        mode: 'read',
+                    }),
+                },
+            },
+        ];
+    }
+    return [];
+}
+/**
+ * Get example from a schema object.
+ */
+export function getExampleFromSchema(args) {
+    var schema = args.schema;
+    if (schema.example) {
+        return { value: schema.example };
+    }
+    return { value: generateSchemaExample(schema, { mode: 'read' }) };
+}
+/**
+ * Get the examples from a media type object.
+ */
+export function getExamples(props) {
+    var mediaTypeObject = props.mediaTypeObject, mediaType = props.mediaType, context = props.context;
+    var examples = getExamplesFromMediaTypeObject({ mediaTypeObject: mediaTypeObject, mediaType: mediaType, context: context });
+    var syntax = getSyntaxFromMediaType(mediaType);
+    return examples.map(function (example) {
+        return {
+            key: example.key,
+            label: example.example.summary || example.key,
+            body: (<OpenAPIExample example={example.example} context={props.context} syntax={syntax}/>),
+        };
+    });
+}
+/**
+ * Get the syntax from a media type.
+ */
+function getSyntaxFromMediaType(mediaType) {
+    if (mediaType.includes('json')) {
+        return 'json';
+    }
+    if (mediaType === 'application/xml') {
+        return 'xml';
+    }
+    return 'text';
+}

package/dist/utils.d.ts

@@ -1,4 +1,5 @@
 import type { AnyObject, OpenAPIV3, OpenAPIV3_1 } from '@gitbook/openapi-parser';
+import type { OpenAPIUniversalContext } from './context';
 export declare function checkIsReference(input: unknown): input is OpenAPIV3.ReferenceObject;
 export declare function createStateKey(key: string, scope?: string): string;
 /**
@@ -29,3 +30,20 @@ export declare function parameterToProperty(parameter: OpenAPIV3.ParameterObject
     schema: OpenAPIV3.SchemaObject;
     required: boolean | undefined;
 };
+/**
+ * Get the class name for a status code.
+ * 1xx: informational
+ * 2xx: success
+ * 3xx: redirect
+ * 4xx, 5xx: error
+ */
+export declare function getStatusCodeClassName(statusCode: number | string): string;
+/**
+ * Get a default label for a status code.
+ * This is used when there is no label provided in the OpenAPI spec.
+ * 1xx: Information
+ * 2xx: Success
+ * 3xx: Redirect
+ * 4xx, 5xx: Error
+ */
+export declare function getStatusCodeDefaultLabel(statusCode: number | string, context: OpenAPIUniversalContext): string;

package/dist/utils.js

@@ -10,6 +10,7 @@ var __assign = (this && this.__assign) || function () {
     return __assign.apply(this, arguments);
 };
 import { stringifyOpenAPI } from './stringifyOpenAPI';
+import { tString } from './translate';
 export function checkIsReference(input) {
     return typeof input === 'object' && !!input && '$ref' in input;
 }
@@ -127,3 +128,59 @@ function shouldDisplayExample(schema) {
             schema.example !== null &&
             Object.keys(schema.example).length > 0));
 }
+/**
+ * Get the class name for a status code.
+ * 1xx: informational
+ * 2xx: success
+ * 3xx: redirect
+ * 4xx, 5xx: error
+ */
+export function getStatusCodeClassName(statusCode) {
+    var category = getStatusCodeCategory(statusCode);
+    switch (category) {
+        case 1:
+            return 'informational';
+        case 2:
+            return 'success';
+        case 3:
+            return 'redirect';
+        case 4:
+        case 5:
+            return 'error';
+        default:
+            return 'unknown';
+    }
+}
+/**
+ * Get a default label for a status code.
+ * This is used when there is no label provided in the OpenAPI spec.
+ * 1xx: Information
+ * 2xx: Success
+ * 3xx: Redirect
+ * 4xx, 5xx: Error
+ */
+export function getStatusCodeDefaultLabel(statusCode, context) {
+    var category = getStatusCodeCategory(statusCode);
+    switch (category) {
+        case 1:
+            return tString(context.translation, 'information');
+        case 2:
+            return tString(context.translation, 'success');
+        case 3:
+            return tString(context.translation, 'redirect');
+        case 4:
+        case 5:
+            return tString(context.translation, 'error');
+        default:
+            return '';
+    }
+}
+function getStatusCodeCategory(statusCode) {
+    var code = typeof statusCode === 'string' ? Number.parseInt(statusCode, 10) : statusCode;
+    if (Number.isNaN(code) || code < 100 || code >= 600) {
+        return 'unknown';
+    }
+    // Determine the category of the status code based on the first digit
+    var category = Math.floor(code / 100);
+    return category;
+}

package/package.json

@@ -8,12 +8,12 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "1.1.10",
+    "version": "1.2.0",
     "sideEffects": false,
     "dependencies": {
         "@gitbook/openapi-parser": "workspace:*",
-        "@scalar/api-client-react": "^1.2.5",
-        "@scalar/oas-utils": "^0.2.120",
+        "@scalar/api-client-react": "^1.2.19",
+        "@scalar/oas-utils": "^0.2.130",
         "clsx": "^2.1.1",
         "flatted": "^3.2.9",
         "json-xml-parse": "^1.3.0",

package/src/InteractiveSection.tsx

@@ -1,10 +1,10 @@
 'use client';
 
 import clsx from 'clsx';
-import { useRef, useState } from 'react';
+import { useRef } from 'react';
 import { mergeProps, useButton, useDisclosure, useFocusRing } from 'react-aria';
 import { useDisclosureState } from 'react-stately';
-import { OpenAPISelect, OpenAPISelectItem } from './OpenAPISelect';
+import { OpenAPISelect, OpenAPISelectItem, useSelectState } from './OpenAPISelect';
 import { Section, SectionBody, SectionHeader, SectionHeaderContent } from './StaticSection';
 
 interface InteractiveSectionTab {
@@ -35,6 +35,10 @@ export function InteractiveSection(props: {
     header?: React.ReactNode;
     /** Children to display within the container */
     overlay?: React.ReactNode;
+    /** State key to use with a store */
+    stateKey?: string;
+    /** Icon for the tabs select */
+    selectIcon?: React.ReactNode;
 }) {
     const {
         id,
@@ -46,12 +50,9 @@ export function InteractiveSection(props: {
         header,
         overlay,
         toggleIcon = '▶',
+        selectIcon,
+        stateKey = 'interactive-section',
     } = props;
-
-    const [selectedTabKey, setSelectedTab] = useState(defaultTab);
-    const selectedTab: InteractiveSectionTab | undefined =
-        tabs.find((tab) => tab.key === selectedTabKey) ?? tabs[0];
-
     const state = useDisclosureState({
         defaultExpanded: defaultOpened,
     });
@@ -60,6 +61,10 @@ export function InteractiveSection(props: {
     const { buttonProps: triggerProps, panelProps } = useDisclosure({}, state, panelRef);
     const { buttonProps } = useButton(triggerProps, triggerRef);
     const { isFocusVisible, focusProps } = useFocusRing();
+    const store = useSelectState(stateKey, defaultTab);
+
+    const selectedTab: InteractiveSectionTab | undefined =
+        tabs.find((tab) => tab.key === store.key) ?? tabs[0];
 
     return (
         <Section
@@ -97,6 +102,7 @@ export function InteractiveSection(props: {
                         ) : null}
                         {header}
                     </SectionHeaderContent>
+                    {/* biome-ignore lint/a11y/useKeyWithClickEvents: we prevent default here */}
                     <div
                         className={clsx(
                             'openapi-section-header-controls',
@@ -108,16 +114,12 @@ export function InteractiveSection(props: {
                     >
                         {tabs.length > 1 ? (
                             <OpenAPISelect
-                                className={clsx(
-                                    'openapi-section-select',
-                                    `${className}-tabs-select`
-                                )}
+                                stateKey={stateKey}
                                 items={tabs}
-                                selectedKey={selectedTab?.key ?? ''}
-                                onSelectionChange={(key) => {
-                                    setSelectedTab(String(key));
+                                onSelectionChange={() => {
                                     state.expand();
                                 }}
+                                icon={selectIcon}
                                 placement="bottom end"
                             >
                                 {tabs.map((tab) => (

package/src/OpenAPICodeSample.tsx

@@ -6,9 +6,10 @@ import {
 import { OpenAPICodeSampleBody } from './OpenAPICodeSampleSelector';
 import { ScalarApiButton } from './ScalarApiButton';
 import { type CodeSampleGenerator, codeSampleGenerators } from './code-samples';
+import { type OpenAPIContext, getOpenAPIClientContext } from './context';
 import { generateMediaTypeExamples, generateSchemaExample } from './generateSchemaExample';
 import { stringifyOpenAPI } from './stringifyOpenAPI';
-import type { OpenAPIContext, OpenAPIOperationData } from './types';
+import type { OpenAPIOperationData } from './types';
 import { getDefaultServerURL } from './util/server';
 import { checkIsReference } from './utils';
 
@@ -22,7 +23,7 @@ export function OpenAPICodeSample(props: {
     data: OpenAPIOperationData;
     context: OpenAPIContext;
 }) {
-    const { data } = props;
+    const { data, context } = props;
 
     // If code samples are disabled at operation level, we don't display the code samples.
     if (data.operation['x-codeSamples'] === false) {
@@ -43,7 +44,14 @@ export function OpenAPICodeSample(props: {
         return null;
     }
 
-    return <OpenAPICodeSampleBody data={data} items={samples} />;
+    return (
+        <OpenAPICodeSampleBody
+            context={getOpenAPIClientContext(context)}
+            data={data}
+            items={samples}
+            selectIcon={context.icons.chevronDown}
+        />
+    );
 }
 
 /**
@@ -146,6 +154,7 @@ function generateCodeSamples(props: {
                         method={data.method}
                         path={data.path}
                         renderers={renderers}
+                        blockKey={context.blockKey}
                     />
                 ),
                 footer: (
@@ -206,11 +215,20 @@ function OpenAPICodeSampleFooter(props: {
                     method={data.method}
                     path={data.path}
                     renderers={renderers}
+                    selectIcon={context.icons.chevronDown}
+                    blockKey={context.blockKey}
                 />
             ) : (
                 <span />
             )}
-            {!hideTryItPanel && <ScalarApiButton method={method} path={path} specUrl={specUrl} />}
+            {!hideTryItPanel && (
+                <ScalarApiButton
+                    context={getOpenAPIClientContext(context)}
+                    method={method}
+                    path={path}
+                    specUrl={specUrl}
+                />
+            )}
         </div>
     );
 }

package/src/OpenAPICodeSampleInteractive.tsx

@@ -1,70 +1,43 @@
 'use client';
 import clsx from 'clsx';
-import { useCallback } from 'react';
-import { useStore } from 'zustand';
 import type { MediaTypeRenderer } from './OpenAPICodeSample';
-import { OpenAPISelect, OpenAPISelectItem } from './OpenAPISelect';
-import { getOrCreateStoreByKey } from './getOrCreateStoreByKey';
-
-type MediaTypeState = {
-    mediaType: string;
-    setMediaType: (mediaType: string) => void;
-};
-
-function useMediaTypeState(
-    data: { method: string; path: string },
-    defaultKey: string
-): MediaTypeState {
-    const { method, path } = data;
-    const store = useStore(getOrCreateStoreByKey(`media-type-${method}-${path}`, defaultKey));
-    if (typeof store.key !== 'string') {
-        throw new Error('Media type key is not a string');
-    }
-    return {
-        mediaType: store.key,
-        setMediaType: useCallback((index: string) => store.setKey(index), [store.setKey]),
-    };
-}
-
-function useMediaTypeSampleIndexState(data: { method: string; path: string }, mediaType: string) {
-    const { method, path } = data;
-    const store = useStore(
-        getOrCreateStoreByKey(`media-type-sample-${mediaType}-${method}-${path}`, 0)
-    );
-    if (typeof store.key !== 'number') {
-        throw new Error('Example key is not a number');
-    }
-    return {
-        index: store.key,
-        setIndex: useCallback((index: number) => store.setKey(index), [store.setKey]),
-    };
-}
+import { OpenAPISelect, OpenAPISelectItem, useSelectState } from './OpenAPISelect';
+import { createStateKey } from './utils';
 
 export function OpenAPIMediaTypeExamplesSelector(props: {
     method: string;
     path: string;
     renderers: MediaTypeRenderer[];
+    selectIcon?: React.ReactNode;
+    blockKey?: string;
 }) {
-    const { method, path, renderers } = props;
+    const { method, path, renderers, selectIcon, blockKey } = props;
     if (!renderers[0]) {
         throw new Error('No renderers provided');
     }
-    const state = useMediaTypeState({ method, path }, renderers[0].mediaType);
-    const selected = renderers.find((r) => r.mediaType === state.mediaType) || renderers[0];
+    const stateKey = createStateKey('request-body-media-type', blockKey);
+    const state = useSelectState(stateKey, renderers[0].mediaType);
+    const selected = renderers.find((r) => r.mediaType === state.key) || renderers[0];
 
     return (
         <div className="openapi-codesample-selectors">
-            <MediaTypeSelector state={state} renderers={renderers} />
-            <ExamplesSelector method={method} path={path} renderer={selected} />
+            <MediaTypeSelector selectIcon={selectIcon} stateKey={stateKey} renderers={renderers} />
+            <ExamplesSelector
+                selectIcon={selectIcon}
+                method={method}
+                path={path}
+                renderer={selected}
+            />
         </div>
     );
 }
 
 function MediaTypeSelector(props: {
-    state: MediaTypeState;
+    stateKey: string;
     renderers: MediaTypeRenderer[];
+    selectIcon?: React.ReactNode;
 }) {
-    const { renderers, state } = props;
+    const { renderers, stateKey, selectIcon } = props;
 
     if (renderers.length < 2) {
         return null;
@@ -78,12 +51,12 @@ function MediaTypeSelector(props: {
     return (
         <OpenAPISelect
             className={clsx('openapi-select')}
-            selectedKey={state.mediaType}
             items={renderers.map((renderer) => ({
                 key: renderer.mediaType,
                 label: renderer.mediaType,
             }))}
-            onSelectionChange={(e) => state.setMediaType(String(e))}
+            icon={selectIcon}
+            stateKey={stateKey}
             placement="bottom start"
         >
             {items.map((item) => (
@@ -99,9 +72,9 @@ function ExamplesSelector(props: {
     method: string;
     path: string;
     renderer: MediaTypeRenderer;
+    selectIcon?: React.ReactNode;
 }) {
-    const { method, path, renderer } = props;
-    const state = useMediaTypeSampleIndexState({ method, path }, renderer.mediaType);
+    const { method, path, renderer, selectIcon } = props;
     if (renderer.examples.length < 2) {
         return null;
     }
@@ -114,8 +87,8 @@ function ExamplesSelector(props: {
     return (
         <OpenAPISelect
             items={items}
-            selectedKey={state.index}
-            onSelectionChange={(e) => state.setIndex(Number(e))}
+            icon={selectIcon}
+            stateKey={`media-type-sample-${renderer.mediaType}-${method}-${path}`}
             placement="bottom start"
         >
             {items.map((item) => (
@@ -131,14 +104,18 @@ export function OpenAPIMediaTypeExamplesBody(props: {
     method: string;
     path: string;
     renderers: MediaTypeRenderer[];
+    blockKey?: string;
 }) {
-    const { renderers, method, path } = props;
+    const { renderers, method, path, blockKey } = props;
     if (!renderers[0]) {
         throw new Error('No renderers provided');
     }
-    const mediaTypeState = useMediaTypeState({ method, path }, renderers[0].mediaType);
-    const selected =
-        renderers.find((r) => r.mediaType === mediaTypeState.mediaType) ?? renderers[0];
+
+    const mediaTypeState = useSelectState(
+        createStateKey('request-body-media-type', blockKey),
+        renderers[0].mediaType
+    );
+    const selected = renderers.find((r) => r.mediaType === mediaTypeState.key) ?? renderers[0];
     if (selected.examples.length === 0) {
         return selected.element;
     }
@@ -147,10 +124,13 @@ export function OpenAPIMediaTypeExamplesBody(props: {
 
 function ExamplesBody(props: { method: string; path: string; renderer: MediaTypeRenderer }) {
     const { method, path, renderer } = props;
-    const exampleState = useMediaTypeSampleIndexState({ method, path }, renderer.mediaType);
-    const example = renderer.examples[exampleState.index] ?? renderer.examples[0];
+    const exampleState = useSelectState(
+        `media-type-sample-${renderer.mediaType}-${method}-${path}`,
+        renderer.mediaType
+    );
+    const example = renderer.examples[Number(exampleState.key)] ?? renderer.examples[0];
     if (!example) {
-        throw new Error(`No example found for index ${exampleState.index}`);
+        throw new Error(`No example found for key ${exampleState.key}`);
     }
     return example.element;
 }