@gitbook/react-openapi 1.1.8 → 1.1.10

package/dist/types.d.ts

@@ -1,5 +1,28 @@
-import type { OpenAPICustomOperationProperties, OpenAPICustomSpecProperties, OpenAPISchema, OpenAPIV3 } from '@gitbook/openapi-parser';
-export interface OpenAPIContextProps extends OpenAPIClientContext {
+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.
      */
@@ -11,7 +34,7 @@ export interface OpenAPIContextProps extends OpenAPIClientContext {
      * Render the heading of the operation.
      */
     renderHeading: (props: {
-        deprecated: boolean;
+        deprecated?: boolean;
         title: string;
         stability?: string;
     }) => React.ReactNode;
@@ -21,27 +44,14 @@ export interface OpenAPIContextProps extends OpenAPIClientContext {
     renderDocument: (props: {
         document: object;
     }) => React.ReactNode;
-    /** Spec url for the Scalar Api Client */
-    specUrl: string;
-}
-export interface OpenAPIClientContext {
-    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
+     * Specification URL.
      */
-    blockKey?: string;
-    /** Optional id attached to the OpenAPI Operation heading and used as an anchor */
-    id?: string;
+    specUrl: string;
 }
+export type OpenAPISecurityWithRequired = OpenAPIV3.SecuritySchemeObject & {
+    required?: boolean;
+};
 export interface OpenAPIOperationData extends OpenAPICustomSpecProperties {
     path: string;
     method: string;
@@ -50,9 +60,5 @@ export interface OpenAPIOperationData extends OpenAPICustomSpecProperties {
     /** Spec of the operation */
     operation: OpenAPIV3.OperationObject<OpenAPICustomOperationProperties>;
     /** Securities that should be used for this operation */
-    securities: [string, OpenAPIV3.SecuritySchemeObject][];
-}
-export interface OpenAPISchemasData {
-    /** Components schemas to be used for schemas */
-    schemas: OpenAPISchema[];
+    securities: [string, OpenAPISecurityWithRequired][];
 }

package/package.json

@@ -8,7 +8,7 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "1.1.8",
+    "version": "1.1.10",
     "sideEffects": false,
     "dependencies": {
         "@gitbook/openapi-parser": "workspace:*",

package/src/InteractiveSection.tsx

@@ -4,6 +4,7 @@ import clsx from 'clsx';
 import { useRef, useState } from 'react';
 import { mergeProps, useButton, useDisclosure, useFocusRing } from 'react-aria';
 import { useDisclosureState } from 'react-stately';
+import { OpenAPISelect, OpenAPISelectItem } from './OpenAPISelect';
 import { Section, SectionBody, SectionHeader, SectionHeaderContent } from './StaticSection';
 
 interface InteractiveSectionTab {
@@ -106,24 +107,25 @@ export function InteractiveSection(props: {
                         }}
                     >
                         {tabs.length > 1 ? (
-                            <select
+                            <OpenAPISelect
                                 className={clsx(
                                     'openapi-section-select',
-                                    'openapi-select',
                                     `${className}-tabs-select`
                                 )}
-                                value={selectedTab?.key ?? ''}
-                                onChange={(event) => {
-                                    setSelectedTab(event.target.value);
+                                items={tabs}
+                                selectedKey={selectedTab?.key ?? ''}
+                                onSelectionChange={(key) => {
+                                    setSelectedTab(String(key));
                                     state.expand();
                                 }}
+                                placement="bottom end"
                             >
                                 {tabs.map((tab) => (
-                                    <option key={tab.key} value={tab.key}>
+                                    <OpenAPISelectItem key={tab.key} id={tab.key} value={tab}>
                                         {tab.label}
-                                    </option>
+                                    </OpenAPISelectItem>
                                 ))}
-                            </select>
+                            </OpenAPISelect>
                         ) : null}
                     </div>
                 </SectionHeader>

package/src/OpenAPICodeSample.tsx

@@ -3,15 +3,14 @@ import {
     OpenAPIMediaTypeExamplesBody,
     OpenAPIMediaTypeExamplesSelector,
 } from './OpenAPICodeSampleInteractive';
-import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
+import { OpenAPICodeSampleBody } from './OpenAPICodeSampleSelector';
 import { ScalarApiButton } from './ScalarApiButton';
-import { StaticSection } from './StaticSection';
 import { type CodeSampleGenerator, codeSampleGenerators } from './code-samples';
 import { generateMediaTypeExamples, generateSchemaExample } from './generateSchemaExample';
 import { stringifyOpenAPI } from './stringifyOpenAPI';
-import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
+import type { OpenAPIContext, OpenAPIOperationData } from './types';
 import { getDefaultServerURL } from './util/server';
-import { checkIsReference, createStateKey } from './utils';
+import { checkIsReference } from './utils';
 
 const CUSTOM_CODE_SAMPLES_KEYS = ['x-custom-examples', 'x-code-samples', 'x-codeSamples'] as const;
 
@@ -21,7 +20,7 @@ const CUSTOM_CODE_SAMPLES_KEYS = ['x-custom-examples', 'x-code-samples', 'x-code
  */
 export function OpenAPICodeSample(props: {
     data: OpenAPIOperationData;
-    context: OpenAPIContextProps;
+    context: OpenAPIContext;
 }) {
     const { data } = props;
 
@@ -44,13 +43,7 @@ export function OpenAPICodeSample(props: {
         return null;
     }
 
-    return (
-        <OpenAPITabs stateKey={createStateKey('codesample')} items={samples}>
-            <StaticSection header={<OpenAPITabsList />} className="openapi-codesample">
-                <OpenAPITabsPanels />
-            </StaticSection>
-        </OpenAPITabs>
-    );
+    return <OpenAPICodeSampleBody data={data} items={samples} />;
 }
 
 /**
@@ -58,7 +51,7 @@ export function OpenAPICodeSample(props: {
  */
 function generateCodeSamples(props: {
     data: OpenAPIOperationData;
-    context: OpenAPIContextProps;
+    context: OpenAPIContext;
 }) {
     const { data, context } = props;
 
@@ -189,7 +182,7 @@ export interface MediaTypeRenderer {
 function OpenAPICodeSampleFooter(props: {
     data: OpenAPIOperationData;
     renderers: MediaTypeRenderer[];
-    context: OpenAPIContextProps;
+    context: OpenAPIContext;
 }) {
     const { data, context, renderers } = props;
     const { method, path } = data;
@@ -227,7 +220,7 @@ function OpenAPICodeSampleFooter(props: {
  */
 function getCustomCodeSamples(props: {
     data: OpenAPIOperationData;
-    context: OpenAPIContextProps;
+    context: OpenAPIContext;
 }) {
     const { data, context } = props;
 

package/src/OpenAPICodeSampleInteractive.tsx

@@ -3,7 +3,8 @@ import clsx from 'clsx';
 import { useCallback } from 'react';
 import { useStore } from 'zustand';
 import type { MediaTypeRenderer } from './OpenAPICodeSample';
-import { getOrCreateTabStoreByKey } from './useSyncedTabsGlobalState';
+import { OpenAPISelect, OpenAPISelectItem } from './OpenAPISelect';
+import { getOrCreateStoreByKey } from './getOrCreateStoreByKey';
 
 type MediaTypeState = {
     mediaType: string;
@@ -15,27 +16,27 @@ function useMediaTypeState(
     defaultKey: string
 ): MediaTypeState {
     const { method, path } = data;
-    const store = useStore(getOrCreateTabStoreByKey(`media-type-${method}-${path}`, defaultKey));
-    if (typeof store.tabKey !== 'string') {
+    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.tabKey,
-        setMediaType: useCallback((index: string) => store.setTabKey(index), [store.setTabKey]),
+        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(
-        getOrCreateTabStoreByKey(`media-type-sample-${mediaType}-${method}-${path}`, 0)
+        getOrCreateStoreByKey(`media-type-sample-${mediaType}-${method}-${path}`, 0)
     );
-    if (typeof store.tabKey !== 'number') {
+    if (typeof store.key !== 'number') {
         throw new Error('Example key is not a number');
     }
     return {
-        index: store.tabKey,
-        setIndex: useCallback((index: number) => store.setTabKey(index), [store.setTabKey]),
+        index: store.key,
+        setIndex: useCallback((index: number) => store.setKey(index), [store.setKey]),
     };
 }
 
@@ -69,18 +70,28 @@ function MediaTypeSelector(props: {
         return null;
     }
 
+    const items = renderers.map((renderer) => ({
+        key: renderer.mediaType,
+        label: renderer.mediaType,
+    }));
+
     return (
-        <select
+        <OpenAPISelect
             className={clsx('openapi-select')}
-            value={state.mediaType}
-            onChange={(e) => state.setMediaType(e.target.value)}
+            selectedKey={state.mediaType}
+            items={renderers.map((renderer) => ({
+                key: renderer.mediaType,
+                label: renderer.mediaType,
+            }))}
+            onSelectionChange={(e) => state.setMediaType(String(e))}
+            placement="bottom start"
         >
-            {renderers.map((renderer) => (
-                <option key={renderer.mediaType} value={renderer.mediaType}>
-                    {renderer.mediaType}
-                </option>
+            {items.map((item) => (
+                <OpenAPISelectItem key={item.key} id={item.key} value={item}>
+                    {item.label}
+                </OpenAPISelectItem>
             ))}
-        </select>
+        </OpenAPISelect>
     );
 }
 
@@ -95,18 +106,24 @@ function ExamplesSelector(props: {
         return null;
     }
 
+    const items = renderer.examples.map((example, index) => ({
+        key: index,
+        label: example.example.summary || `Example ${index + 1}`,
+    }));
+
     return (
-        <select
-            className={clsx('openapi-select')}
-            value={String(state.index)}
-            onChange={(e) => state.setIndex(Number(e.target.value))}
+        <OpenAPISelect
+            items={items}
+            selectedKey={state.index}
+            onSelectionChange={(e) => state.setIndex(Number(e))}
+            placement="bottom start"
         >
-            {renderer.examples.map((example, index) => (
-                <option key={index} value={index}>
-                    {example.example.summary || `Example ${index + 1}`}
-                </option>
+            {items.map((item) => (
+                <OpenAPISelectItem key={item.key} id={item.key} value={item}>
+                    {item.label}
+                </OpenAPISelectItem>
             ))}
-        </select>
+        </OpenAPISelect>
     );
 }
 

package/src/OpenAPICodeSampleSelector.tsx

@@ -0,0 +1,87 @@
+'use client';
+
+import { useCallback } from 'react';
+import type { Key } from 'react-aria';
+import { useStore } from 'zustand';
+import { OpenAPIPath } from './OpenAPIPath';
+import { OpenAPISelect, OpenAPISelectItem } from './OpenAPISelect';
+import { StaticSection } from './StaticSection';
+import { getOrCreateStoreByKey } from './getOrCreateStoreByKey';
+import type { OpenAPIOperationData } from './types';
+
+function useCodeSampleState(initialKey: Key = 'default') {
+    const store = useStore(getOrCreateStoreByKey('codesample', initialKey));
+    return {
+        key: store.key,
+        setKey: useCallback((key: Key) => store.setKey(key), [store.setKey]),
+    };
+}
+
+type CodeSampleItem = OpenAPISelectItem & {
+    body: React.ReactNode;
+    footer?: React.ReactNode;
+};
+
+export function OpenAPICodeSampleHeader(props: {
+    items: CodeSampleItem[];
+    data: OpenAPIOperationData;
+}) {
+    const { data, items } = props;
+
+    const state = useCodeSampleState(items[0]?.key ?? '');
+    const selected = items.find((item) => item.key === state.key) || items[0];
+
+    return (
+        <>
+            <OpenAPIPath canCopy={false} withServer={false} data={data} />
+            {items.length > 1 ? (
+                <OpenAPISelect
+                    selectedKey={selected?.key}
+                    onSelectionChange={(key) => {
+                        state.setKey(key);
+                    }}
+                    items={items}
+                    placement="bottom end"
+                >
+                    {items.map((item) => (
+                        <OpenAPISelectItem key={item.key} id={item.key} value={item}>
+                            {item.label}
+                        </OpenAPISelectItem>
+                    ))}
+                </OpenAPISelect>
+            ) : items[0] ? (
+                <span className="openapi-codesample-label">{items[0].label}</span>
+            ) : null}
+        </>
+    );
+}
+
+export function OpenAPICodeSampleBody(props: {
+    items: CodeSampleItem[];
+    data: OpenAPIOperationData;
+}) {
+    const { items, data } = props;
+    if (!items[0]) {
+        throw new Error('No items provided');
+    }
+
+    const state = useCodeSampleState(items[0]?.key);
+
+    const selected = items.find((item) => item.key === state.key) || items[0];
+
+    if (!selected) {
+        return null;
+    }
+
+    return (
+        <StaticSection
+            header={<OpenAPICodeSampleHeader data={data} items={items} />}
+            className="openapi-codesample"
+        >
+            <div id={selected.key as string} className="openapi-codesample-panel">
+                {selected.body ? selected.body : null}
+                {selected.footer ? selected.footer : null}
+            </div>
+        </StaticSection>
+    );
+}

package/src/OpenAPIExample.tsx

@@ -0,0 +1,129 @@
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import { generateSchemaExample } from './generateSchemaExample';
+import { json2xml } from './json2xml';
+import { stringifyOpenAPI } from './stringifyOpenAPI';
+import type { OpenAPIContext } from './types';
+import { checkIsReference } from './utils';
+
+/**
+ * Display an example.
+ */
+export function OpenAPIExample(props: {
+    example: OpenAPIV3.ExampleObject;
+    context: OpenAPIContext;
+    syntax: string;
+}) {
+    const { example, context, syntax } = props;
+    const code = stringifyExample({ example, xml: syntax === 'xml' });
+
+    if (code === null) {
+        return <OpenAPIEmptyExample />;
+    }
+
+    return context.renderCodeBlock({ code, syntax });
+}
+
+function stringifyExample(args: { example: OpenAPIV3.ExampleObject; xml: boolean }): string | null {
+    const { example, xml } = args;
+
+    if (!example.value) {
+        return null;
+    }
+
+    if (typeof example.value === 'string') {
+        return example.value;
+    }
+
+    if (xml) {
+        return json2xml(example.value);
+    }
+
+    return stringifyOpenAPI(example.value, null, 2);
+}
+
+/**
+ * Empty response example.
+ */
+export function OpenAPIEmptyExample() {
+    return (
+        <pre className="openapi-example-empty">
+            <p>No Content</p>
+        </pre>
+    );
+}
+
+/**
+ * Generate an example from a reference object.
+ */
+export function getExampleFromReference(ref: OpenAPIV3.ReferenceObject): OpenAPIV3.ExampleObject {
+    return { summary: 'Unresolved reference', value: { $ref: ref.$ref } };
+}
+
+/**
+ * Get examples from a media type object.
+ */
+export function getExamplesFromMediaTypeObject(args: {
+    mediaType: string;
+    mediaTypeObject: OpenAPIV3.MediaTypeObject;
+}): { key: string; example: OpenAPIV3.ExampleObject }[] {
+    const { mediaTypeObject, mediaType } = args;
+    if (mediaTypeObject.examples) {
+        return Object.entries(mediaTypeObject.examples).map(([key, example]) => {
+            return {
+                key,
+                example: checkIsReference(example) ? getExampleFromReference(example) : 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
+            const root = mediaTypeObject.schema.xml?.name ?? 'object';
+            return [
+                {
+                    key: 'default',
+                    example: {
+                        value: {
+                            [root]: generateSchemaExample(mediaTypeObject.schema, {
+                                xml: mediaType === 'application/xml',
+                                mode: 'read',
+                            }),
+                        },
+                    },
+                },
+            ];
+        }
+        return [
+            {
+                key: 'default',
+                example: {
+                    value: generateSchemaExample(mediaTypeObject.schema, {
+                        mode: 'read',
+                    }),
+                },
+            },
+        ];
+    }
+    return [];
+}
+
+/**
+ * Get example from a schema object.
+ */
+export function getExampleFromSchema(args: {
+    schema: OpenAPIV3.SchemaObject;
+}): OpenAPIV3.ExampleObject {
+    const { schema } = args;
+
+    if (schema.example) {
+        return { value: schema.example };
+    }
+
+    return { value: generateSchemaExample(schema, { mode: 'read' }) };
+}

package/src/OpenAPIOperation.tsx

@@ -10,7 +10,8 @@ import { OpenAPICodeSample } from './OpenAPICodeSample';
 import { OpenAPIPath } from './OpenAPIPath';
 import { OpenAPIResponseExample } from './OpenAPIResponseExample';
 import { OpenAPISpec } from './OpenAPISpec';
-import type { OpenAPIClientContext, OpenAPIContextProps, OpenAPIOperationData } from './types';
+import { getOpenAPIClientContext } from './context';
+import type { OpenAPIContext, OpenAPIOperationData } from './types';
 import { resolveDescription } from './utils';
 
 /**
@@ -19,16 +20,12 @@ import { resolveDescription } from './utils';
 export function OpenAPIOperation(props: {
     className?: string;
     data: OpenAPIOperationData;
-    context: OpenAPIContextProps;
+    context: OpenAPIContext;
 }) {
     const { className, data, context } = props;
     const { operation } = data;
 
-    const clientContext: OpenAPIClientContext = {
-        defaultInteractiveOpened: context.defaultInteractiveOpened,
-        icons: context.icons,
-        blockKey: context.blockKey,
-    };
+    const clientContext = getOpenAPIClientContext(context);
 
     return (
         <div className={clsx('openapi-operation', className)}>
@@ -50,7 +47,7 @@ export function OpenAPIOperation(props: {
                           title: operation.summary,
                       })
                     : null}
-                <OpenAPIPath data={data} context={context} />
+                <OpenAPIPath data={data} />
             </div>
             <div className="openapi-columns">
                 <div className="openapi-column-spec">
@@ -79,7 +76,7 @@ export function OpenAPIOperation(props: {
 
 function OpenAPIOperationDescription(props: {
     operation: OpenAPIV3.OperationObject<OpenAPICustomOperationProperties>;
-    context: OpenAPIContextProps;
+    context: OpenAPIContext;
 }) {
     const { operation } = props;
     if (operation['x-gitbook-description-document']) {
@@ -108,7 +105,6 @@ const stabilityEnum = {
     experimental: 'Experimental',
     alpha: 'Alpha',
     beta: 'Beta',
-    stable: 'Stable',
 } as const;
 
 function OpenAPIOperationStability(props: { stability: OpenAPIStability }) {

package/src/OpenAPIPath.tsx

@@ -1,5 +1,5 @@
 import { OpenAPICopyButton } from './OpenAPICopyButton';
-import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
+import type { OpenAPIOperationData } from './types';
 import { getDefaultServerURL } from './util/server';
 
 /**
@@ -7,25 +7,42 @@ import { getDefaultServerURL } from './util/server';
  */
 export function OpenAPIPath(props: {
     data: OpenAPIOperationData;
-    context: OpenAPIContextProps;
+    /** Whether to show the server URL.
+     * @default true
+     */
+    withServer?: boolean;
+    /**
+     * Whether the path is copyable.
+     * @default true
+     */
+    canCopy?: boolean;
 }) {
-    const { data } = props;
+    const { data, withServer = true, canCopy = true } = props;
     const { method, path, operation } = data;
 
     const server = getDefaultServerURL(data.servers);
     const formattedPath = formatPath(path);
 
+    const element = (() => {
+        return (
+            <>
+                {withServer ? <span className="openapi-path-server">{server}</span> : null}
+                {formattedPath}
+            </>
+        );
+    })();
+
     return (
         <div className="openapi-path">
             <div className={`openapi-method openapi-method-${method}`}>{method}</div>
 
             <OpenAPICopyButton
-                value={server + path}
+                value={`${withServer ? server : ''}${path}`}
                 className="openapi-path-title"
                 data-deprecated={operation.deprecated}
+                isDisabled={!canCopy}
             >
-                <span className="openapi-path-server">{server}</span>
-                {formattedPath}
+                {element}
             </OpenAPICopyButton>
         </div>
     );

package/src/OpenAPIResponse.tsx

@@ -36,13 +36,15 @@ export function OpenAPIResponse(props: {
                     />
                 </OpenAPIDisclosure>
             ) : null}
-            <div className="openapi-responsebody">
-                <OpenAPISchemaProperties
-                    id={`response-${context.blockKey}`}
-                    properties={mediaType.schema ? [{ schema: mediaType.schema }] : []}
-                    context={context}
-                />
-            </div>
+            {mediaType.schema && (
+                <div className="openapi-responsebody">
+                    <OpenAPISchemaProperties
+                        id={`response-${context.blockKey}`}
+                        properties={[{ schema: mediaType.schema }]}
+                        context={context}
+                    />
+                </div>
+            )}
         </div>
     );
 }