@gitbook/react-openapi 1.1.8 → 1.1.10

package/src/OpenAPIResponseExample.tsx

@@ -1,11 +1,14 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import { Markdown } from './Markdown';
+import {
+    OpenAPIEmptyExample,
+    OpenAPIExample,
+    getExampleFromReference,
+    getExamplesFromMediaTypeObject,
+} from './OpenAPIExample';
 import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
 import { StaticSection } from './StaticSection';
-import { generateSchemaExample } from './generateSchemaExample';
-import { json2xml } from './json2xml';
-import { stringifyOpenAPI } from './stringifyOpenAPI';
-import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
+import type { OpenAPIContext, OpenAPIOperationData } from './types';
 import { checkIsReference, createStateKey, resolveDescription } from './utils';
 
 /**
@@ -13,7 +16,7 @@ import { checkIsReference, createStateKey, resolveDescription } from './utils';
  */
 export function OpenAPIResponseExample(props: {
     data: OpenAPIOperationData;
-    context: OpenAPIContextProps;
+    context: OpenAPIContext;
 }) {
     const { data, context } = props;
 
@@ -62,7 +65,7 @@ export function OpenAPIResponseExample(props: {
             return {
                 key: key,
                 label: key,
-                body: <OpenAPIEmptyResponseExample />,
+                body: <OpenAPIEmptyExample />,
                 footer: description ? <Markdown source={description} /> : undefined,
             };
         }
@@ -81,7 +84,7 @@ export function OpenAPIResponseExample(props: {
 
     return (
         <OpenAPITabs stateKey={createStateKey('response-example')} items={tabs}>
-            <StaticSection header={<OpenAPITabsList />} className="openapi-response-example">
+            <StaticSection header={<OpenAPITabsList />} className="openapi-panel">
                 <OpenAPITabsPanels />
             </StaticSection>
         </OpenAPITabs>
@@ -89,7 +92,7 @@ export function OpenAPIResponseExample(props: {
 }
 
 function OpenAPIResponse(props: {
-    context: OpenAPIContextProps;
+    context: OpenAPIContext;
     content: {
         [media: string]: OpenAPIV3.MediaTypeObject;
     };
@@ -141,7 +144,7 @@ function OpenAPIResponse(props: {
 function OpenAPIResponseMediaType(props: {
     mediaTypeObject: OpenAPIV3.MediaTypeObject;
     mediaType: string;
-    context: OpenAPIContextProps;
+    context: OpenAPIContext;
 }) {
     const { mediaTypeObject, mediaType } = props;
     const examples = getExamplesFromMediaTypeObject({ mediaTypeObject, mediaType });
@@ -149,7 +152,7 @@ function OpenAPIResponseMediaType(props: {
     const firstExample = examples[0];
 
     if (!firstExample) {
-        return <OpenAPIEmptyResponseExample />;
+        return <OpenAPIEmptyExample />;
     }
 
     if (examples.length === 1) {
@@ -184,42 +187,6 @@ function OpenAPIResponseMediaType(props: {
     );
 }
 
-/**
- * Display an example.
- */
-function OpenAPIExample(props: {
-    example: OpenAPIV3.ExampleObject;
-    context: OpenAPIContextProps;
-    syntax: string;
-}) {
-    const { example, context, syntax } = props;
-    const code = stringifyExample({ example, xml: syntax === 'xml' });
-
-    if (code === null) {
-        return <OpenAPIEmptyResponseExample />;
-    }
-
-    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);
-}
-
 /**
  * Get the syntax from a media type.
  */
@@ -234,70 +201,3 @@ function getSyntaxFromMediaType(mediaType: string): string {
 
     return 'text';
 }
-
-/**
- * Get examples from a media type object.
- */
-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',
-                            }),
-                        },
-                    },
-                },
-            ];
-        }
-        return [
-            {
-                key: 'default',
-                example: { value: generateSchemaExample(mediaTypeObject.schema) },
-            },
-        ];
-    }
-    return [];
-}
-
-/**
- * Empty response example.
- */
-function OpenAPIEmptyResponseExample() {
-    return (
-        <pre className="openapi-response-example-empty">
-            <p>No body</p>
-        </pre>
-    );
-}
-
-/**
- * Generate an example from a reference object.
- */
-function getExampleFromReference(ref: OpenAPIV3.ReferenceObject): OpenAPIV3.ExampleObject {
-    return { summary: 'Unresolved reference', value: { $ref: ref.$ref } };
-}

package/src/OpenAPIResponses.tsx

@@ -21,7 +21,42 @@ export function OpenAPIResponses(props: {
                 icon={context.icons.chevronRight}
                 groups={Object.entries(responses).map(
                     ([statusCode, response]: [string, OpenAPIV3.ResponseObject]) => {
-                        const content = Object.entries(response.content ?? {});
+                        const tabs = (() => {
+                            // If there is no content, but there are headers, we need to show the headers
+                            if (
+                                (!response.content || !Object.keys(response.content).length) &&
+                                response.headers &&
+                                Object.keys(response.headers).length
+                            ) {
+                                return [
+                                    {
+                                        id: 'default',
+                                        body: (
+                                            <OpenAPIResponse
+                                                response={response}
+                                                mediaType={{}}
+                                                context={context}
+                                            />
+                                        ),
+                                    },
+                                ];
+                            }
+
+                            return Object.entries(response.content ?? {}).map(
+                                ([contentType, mediaType]) => ({
+                                    id: contentType,
+                                    label: contentType,
+                                    body: (
+                                        <OpenAPIResponse
+                                            response={response}
+                                            mediaType={mediaType}
+                                            context={context}
+                                        />
+                                    ),
+                                })
+                            );
+                        })();
+
                         const description = response.description;
 
                         return {
@@ -39,17 +74,7 @@ export function OpenAPIResponses(props: {
                                     ) : null}
                                 </div>
                             ),
-                            tabs: content.map(([contentType, mediaType]) => ({
-                                id: contentType,
-                                label: contentType,
-                                body: (
-                                    <OpenAPIResponse
-                                        response={response}
-                                        mediaType={mediaType}
-                                        context={context}
-                                    />
-                                ),
-                            })),
+                            tabs,
                         };
                     }
                 )}

package/src/OpenAPISchema.tsx

@@ -11,6 +11,7 @@ import { OpenAPICopyButton } from './OpenAPICopyButton';
 import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 import { OpenAPISchemaName } from './OpenAPISchemaName';
 import { retrocycle } from './decycle';
+import { stringifyOpenAPI } from './stringifyOpenAPI';
 import type { OpenAPIClientContext } from './types';
 import { checkIsReference, resolveDescription, resolveFirstExample } from './utils';
 
@@ -145,17 +146,23 @@ function OpenAPIRootSchema(props: {
 
     const id = useId();
     const properties = getSchemaProperties(schema);
+    const description = resolveDescription(schema);
 
     if (properties?.length) {
         const circularRefs = new Map(parentCircularRefs);
         circularRefs.set(schema, id);
 
         return (
-            <OpenAPISchemaProperties
-                properties={properties}
-                circularRefs={circularRefs}
-                context={context}
-            />
+            <>
+                {description ? (
+                    <Markdown source={description} className="openapi-schema-root-description" />
+                ) : null}
+                <OpenAPISchemaProperties
+                    properties={properties}
+                    circularRefs={circularRefs}
+                    context={context}
+                />
+            </>
         );
     }
 
@@ -275,22 +282,20 @@ function OpenAPISchemaEnum(props: {
     }
 
     return (
-        <div className="openapi-schema-enum">
-            <span>Available options:</span>
-            <div className="openapi-schema-enum-list">
-                {enumValues.map((item, index) => (
-                    <span key={index} className="openapi-schema-enum-value">
-                        <OpenAPICopyButton
-                            value={item.value}
-                            label={item.description}
-                            withTooltip={!!item.description}
-                        >
-                            <code>{`${item.value}`}</code>
-                        </OpenAPICopyButton>
-                    </span>
-                ))}
-            </div>
-        </div>
+        <span className="openapi-schema-enum">
+            Available options:{' '}
+            {enumValues.map((item, index) => (
+                <span key={index} className="openapi-schema-enum-value">
+                    <OpenAPICopyButton
+                        value={item.value}
+                        label={item.description}
+                        withTooltip={!!item.description}
+                    >
+                        <code>{`${item.value}`}</code>
+                    </OpenAPICopyButton>
+                </span>
+            ))}
+        </span>
     );
 }
 
@@ -324,15 +329,25 @@ function OpenAPISchemaPresentation(props: { property: OpenAPISchemaPropertyEntry
             {description ? (
                 <Markdown source={description} className="openapi-schema-description" />
             ) : null}
+            {schema.default !== undefined ? (
+                <span className="openapi-schema-default">
+                    Default:{' '}
+                    <code>
+                        {typeof schema.default === 'string' && schema.default
+                            ? schema.default
+                            : stringifyOpenAPI(schema.default)}
+                    </code>
+                </span>
+            ) : null}
             {typeof example === 'string' ? (
-                <div className="openapi-schema-example">
+                <span className="openapi-schema-example">
                     Example: <code>{example}</code>
-                </div>
+                </span>
             ) : null}
             {schema.pattern ? (
-                <div className="openapi-schema-pattern">
+                <span className="openapi-schema-pattern">
                     Pattern: <code>{schema.pattern}</code>
-                </div>
+                </span>
             ) : null}
             <OpenAPISchemaEnum schema={schema} />
         </div>

package/src/OpenAPISchemaName.tsx

@@ -1,6 +1,5 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import type React from 'react';
-import { stringifyOpenAPI } from './stringifyOpenAPI';
 
 interface OpenAPISchemaNameProps {
     schema?: OpenAPIV3.SchemaObject;
@@ -19,7 +18,7 @@ export function OpenAPISchemaName(props: OpenAPISchemaNameProps) {
     const additionalItems = schema && getAdditionalItems(schema);
 
     return (
-        <div className="openapi-schema-name">
+        <span className="openapi-schema-name">
             {propertyName ? (
                 <span data-deprecated={schema?.deprecated} className="openapi-schema-propertyname">
                     {propertyName}
@@ -41,7 +40,7 @@ export function OpenAPISchemaName(props: OpenAPISchemaNameProps) {
                 <span className="openapi-schema-optional">optional</span>
             )}
             {schema?.deprecated ? <span className="openapi-deprecated">Deprecated</span> : null}
-        </div>
+        </span>
     );
 }
 
@@ -56,11 +55,6 @@ function getAdditionalItems(schema: OpenAPIV3.SchemaObject): string {
         additionalItems += ` · max: ${schema.maximum || schema.maxLength || schema.maxItems}`;
     }
 
-    // If the schema has a default value, we display it
-    if (typeof schema.default !== 'undefined') {
-        additionalItems += ` · default: ${stringifyOpenAPI(schema.default)}`;
-    }
-
     if (schema.nullable) {
         additionalItems = ' | nullable';
     }

package/src/OpenAPISecurities.tsx

@@ -1,8 +1,11 @@
-import type { OpenAPIV3_1 } from '@gitbook/openapi-parser';
 import { InteractiveSection } from './InteractiveSection';
 import { Markdown } from './Markdown';
 import { OpenAPISchemaName } from './OpenAPISchemaName';
-import type { OpenAPIClientContext, OpenAPIOperationData } from './types';
+import type {
+    OpenAPIClientContext,
+    OpenAPIOperationData,
+    OpenAPISecurityWithRequired,
+} from './types';
 import { resolveDescription } from './utils';
 
 /**
@@ -50,26 +53,36 @@ export function OpenAPISecurities(props: {
     );
 }
 
-function getLabelForType(security: OpenAPIV3_1.SecuritySchemeObject) {
+function getLabelForType(security: OpenAPISecurityWithRequired) {
     switch (security.type) {
         case 'apiKey':
             return (
                 <OpenAPISchemaName
                     propertyName={security.name ?? 'apiKey'}
                     type="string"
-                    required
+                    required={security.required}
                 />
             );
         case 'http':
             if (security.scheme === 'basic') {
-                return <OpenAPISchemaName propertyName="Authorization" type="string" required />;
+                return (
+                    <OpenAPISchemaName
+                        propertyName="Authorization"
+                        type="string"
+                        required={security.required}
+                    />
+                );
             }
 
             if (security.scheme === 'bearer') {
                 const description = resolveDescription(security);
                 return (
                     <>
-                        <OpenAPISchemaName propertyName="Authorization" type="string" required />
+                        <OpenAPISchemaName
+                            propertyName="Authorization"
+                            type="string"
+                            required={security.required}
+                        />
                         {/** Show a default description if none is provided */}
                         {!description ? (
                             <Markdown
@@ -81,11 +94,11 @@ function getLabelForType(security: OpenAPIV3_1.SecuritySchemeObject) {
                 );
             }
 
-            return <OpenAPISchemaName propertyName="HTTP" required />;
+            return <OpenAPISchemaName propertyName="HTTP" required={security.required} />;
         case 'oauth2':
-            return <OpenAPISchemaName propertyName="OAuth2" required />;
+            return <OpenAPISchemaName propertyName="OAuth2" required={security.required} />;
         case 'openIdConnect':
-            return <OpenAPISchemaName propertyName="OpenID Connect" required />;
+            return <OpenAPISchemaName propertyName="OpenID Connect" required={security.required} />;
         default:
             // @ts-ignore
             return security.type;

package/src/OpenAPISelect.tsx

@@ -0,0 +1,70 @@
+'use client';
+
+import clsx from 'clsx';
+import {
+    Button,
+    type Key,
+    ListBox,
+    ListBoxItem,
+    type ListBoxItemProps,
+    Popover,
+    type PopoverProps,
+    Select,
+    type SelectProps,
+    SelectValue,
+} from 'react-aria-components';
+
+export type OpenAPISelectItem = {
+    key: Key;
+    label: string;
+};
+
+interface OpenAPISelectProps<T extends OpenAPISelectItem> extends Omit<SelectProps<T>, 'children'> {
+    items: T[];
+    children: React.ReactNode | ((item: T) => React.ReactNode);
+    selectedKey?: Key;
+    onChange?: (key: string | number) => void;
+    placement?: PopoverProps['placement'];
+}
+
+export function OpenAPISelect<T extends OpenAPISelectItem>(props: OpenAPISelectProps<T>) {
+    const { items, children, className, placement } = props;
+
+    return (
+        <Select {...props} className={clsx('openapi-select', className)}>
+            <Button>
+                <SelectValue />
+                <span aria-hidden="true">
+                    <svg
+                        className="gb-icon"
+                        style={{
+                            maskImage:
+                                "url('https://ka-p.fontawesome.com/releases/v6.6.0/svgs/regular/chevron-down.svg?v=2&token=a463935e93')",
+                            maskRepeat: 'no-repeat',
+                            maskPosition: 'center center',
+                        }}
+                    />
+                </span>
+            </Button>
+            <Popover placement={placement} className="openapi-select-popover">
+                <ListBox className="openapi-select-listbox" items={items}>
+                    {children}
+                </ListBox>
+            </Popover>
+        </Select>
+    );
+}
+
+export function OpenAPISelectItem(props: ListBoxItemProps) {
+    return (
+        <ListBoxItem
+            {...props}
+            className={({ isFocused, isSelected }) =>
+                clsx('openapi-select-item', {
+                    'openapi-select-item-focused': isFocused,
+                    'openapi-select-item-selected': isSelected,
+                })
+            }
+        />
+    );
+}

package/src/OpenAPITabs.tsx

@@ -3,7 +3,7 @@
 import { createContext, useContext, useEffect, useMemo, useRef, useState } from 'react';
 import { type Key, Tab, TabList, TabPanel, Tabs, type TabsProps } from 'react-aria-components';
 import { useEventCallback } from 'usehooks-ts';
-import { getOrCreateTabStoreByKey } from './useSyncedTabsGlobalState';
+import { getOrCreateStoreByKey } from './getOrCreateStoreByKey';
 
 export type TabItem = {
     key: Key;
@@ -36,8 +36,8 @@ export function OpenAPITabs(
     const { children, items, stateKey } = props;
     const [tabKey, setTabKey] = useState<Key | null>(() => {
         if (stateKey && typeof window !== 'undefined') {
-            const store = getOrCreateTabStoreByKey(stateKey);
-            const tabKey = store.getState().tabKey;
+            const store = getOrCreateStoreByKey(stateKey);
+            const tabKey = store.getState().key;
             if (tabKey) {
                 return tabKey;
             }
@@ -60,10 +60,10 @@ export function OpenAPITabs(
         if (!stateKey) {
             return undefined;
         }
-        const store = getOrCreateTabStoreByKey(stateKey);
+        const store = getOrCreateStoreByKey(stateKey);
         return store.subscribe((state) => {
             cancelDeferRef.current?.();
-            cancelDeferRef.current = defer(() => selectTab(state.tabKey));
+            cancelDeferRef.current = defer(() => selectTab(state.key));
         });
     }, [stateKey, selectTab]);
     useEffect(() => {
@@ -77,8 +77,8 @@ export function OpenAPITabs(
                 onSelectionChange={(tabKey) => {
                     selectTab(tabKey);
                     if (stateKey) {
-                        const store = getOrCreateTabStoreByKey(stateKey);
-                        store.setState({ tabKey });
+                        const store = getOrCreateStoreByKey(stateKey);
+                        store.setState({ key: tabKey });
                     }
                 }}
                 selectedKey={tabKey}
@@ -138,9 +138,9 @@ export function OpenAPITabsPanels() {
 
     return (
         <TabPanel id={key} className="openapi-tabs-panel">
-            <div className="openapi-tabs-body">{selectedTab.body}</div>
+            <div className="openapi-panel-body">{selectedTab.body}</div>
             {selectedTab.footer ? (
-                <div className="openapi-tabs-footer">{selectedTab.footer}</div>
+                <div className="openapi-panel-footer">{selectedTab.footer}</div>
             ) : null}
         </TabPanel>
     );

package/src/context.ts

@@ -0,0 +1,64 @@
+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;
+}
+
+/**
+ * Get the client context from the OpenAPI context.
+ */
+export function getOpenAPIClientContext(context: OpenAPIContext): OpenAPIClientContext {
+    return {
+        icons: context.icons,
+        defaultInteractiveOpened: context.defaultInteractiveOpened,
+        blockKey: context.blockKey,
+        id: context.id,
+    };
+}