@gitbook/react-openapi 1.1.9 → 1.2.0

package/src/OpenAPISchema.test.ts

@@ -35,6 +35,86 @@ describe('getSchemaAlternatives', () => {
         ]);
     });
 
+    it('merges string enum', () => {
+        expect(
+            getSchemaAlternatives({
+                oneOf: [
+                    {
+                        oneOf: [
+                            {
+                                type: 'string',
+                                enum: ['a', 'b'],
+                            },
+                            {
+                                type: 'string',
+                                enum: ['c', 'd'],
+                                nullable: true,
+                            },
+                        ],
+                    },
+                ],
+            })
+        ).toEqual([
+            {
+                type: 'string',
+                enum: ['a', 'b', 'c', 'd'],
+                nullable: true,
+            },
+        ]);
+    });
+
+    it('merges objects with allOf', () => {
+        expect(
+            getSchemaAlternatives({
+                allOf: [
+                    {
+                        type: 'object',
+                        properties: {
+                            name: {
+                                type: 'string',
+                            },
+                            map: {
+                                type: 'string',
+                            },
+                            description: {
+                                type: 'string',
+                            },
+                        },
+                        required: ['name'],
+                    },
+                    {
+                        type: 'object',
+                        properties: {
+                            externalId: {
+                                type: 'string',
+                            },
+                        },
+                        required: ['map', 'externalId'],
+                    },
+                ],
+            })
+        ).toEqual([
+            {
+                type: 'object',
+                properties: {
+                    name: {
+                        type: 'string',
+                    },
+                    map: {
+                        type: 'string',
+                    },
+                    description: {
+                        type: 'string',
+                    },
+                    externalId: {
+                        type: 'string',
+                    },
+                },
+                required: ['name', 'map', 'externalId'],
+            },
+        ]);
+    });
+
     it('should not flatten oneOf and allOf', () => {
         expect(
             getSchemaAlternatives({

package/src/OpenAPISchema.tsx

@@ -10,8 +10,10 @@ import { Markdown } from './Markdown';
 import { OpenAPICopyButton } from './OpenAPICopyButton';
 import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 import { OpenAPISchemaName } from './OpenAPISchemaName';
+import type { OpenAPIClientContext } from './context';
 import { retrocycle } from './decycle';
-import type { OpenAPIClientContext } from './types';
+import { stringifyOpenAPI } from './stringifyOpenAPI';
+import { tString } from './translate';
 import { checkIsReference, resolveDescription, resolveFirstExample } from './utils';
 
 type CircularRefsIds = Map<OpenAPIV3.SchemaObject, string>;
@@ -39,7 +41,7 @@ function OpenAPISchemaProperty(props: {
 
     return (
         <div id={id} className={clsx('openapi-schema', className)}>
-            <OpenAPISchemaPresentation property={property} />
+            <OpenAPISchemaPresentation context={context} property={property} />
             {(() => {
                 const circularRefId = parentCircularRefs.get(schema);
                 // Avoid recursing infinitely, and instead render a link to the parent schema
@@ -53,7 +55,12 @@ function OpenAPISchemaProperty(props: {
                 const properties = getSchemaProperties(schema);
                 if (properties?.length) {
                     return (
-                        <OpenAPIDisclosure context={context} label={getDisclosureLabel(schema)}>
+                        <OpenAPIDisclosure
+                            icon={context.icons.plus}
+                            label={(isExpanded) =>
+                                getDisclosureLabel({ schema, isExpanded, context })
+                            }
+                        >
                             <OpenAPISchemaProperties
                                 properties={properties}
                                 circularRefs={circularRefs}
@@ -145,17 +152,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}
+                />
+            </>
         );
     }
 
@@ -201,7 +214,10 @@ function OpenAPISchemaAlternative(props: {
             {description ? (
                 <Markdown source={description} className="openapi-schema-description" />
             ) : null}
-            <OpenAPIDisclosure context={context} label={getDisclosureLabel(schema)}>
+            <OpenAPIDisclosure
+                icon={context.icons.plus}
+                label={(isExpanded) => getDisclosureLabel({ schema, isExpanded, context })}
+            >
                 {properties?.length ? (
                     <OpenAPISchemaProperties
                         properties={properties}
@@ -239,8 +255,9 @@ function OpenAPISchemaCircularRef(props: { id: string; schema: OpenAPIV3.SchemaO
  */
 function OpenAPISchemaEnum(props: {
     schema: OpenAPIV3.SchemaObject & OpenAPICustomOperationProperties;
+    context: OpenAPIClientContext;
 }) {
-    const { schema } = props;
+    const { schema, context } = props;
 
     const enumValues = (() => {
         // Render x-gitbook-enum first, as it has a different format
@@ -283,6 +300,7 @@ function OpenAPISchemaEnum(props: {
                         value={item.value}
                         label={item.description}
                         withTooltip={!!item.description}
+                        context={context}
                     >
                         <code>{`${item.value}`}</code>
                     </OpenAPICopyButton>
@@ -295,9 +313,13 @@ function OpenAPISchemaEnum(props: {
 /**
  * Render the top row of a schema. e.g: name, type, and required status.
  */
-function OpenAPISchemaPresentation(props: { property: OpenAPISchemaPropertyEntry }) {
+function OpenAPISchemaPresentation(props: {
+    property: OpenAPISchemaPropertyEntry;
+    context: OpenAPIClientContext;
+}) {
     const {
         property: { schema, propertyName, required },
+        context,
     } = props;
 
     const description = resolveDescription(schema);
@@ -310,6 +332,7 @@ function OpenAPISchemaPresentation(props: { property: OpenAPISchemaPropertyEntry
                 type={getSchemaTitle(schema)}
                 propertyName={propertyName}
                 required={required}
+                context={context}
             />
             {typeof schema['x-deprecated-sunset'] === 'string' ? (
                 <div className="openapi-deprecated-sunset openapi-schema-description openapi-markdown">
@@ -322,17 +345,27 @@ 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} />
+            <OpenAPISchemaEnum schema={schema} context={context} />
         </div>
     );
 }
@@ -427,7 +460,91 @@ export function getSchemaAlternatives(
     }
 
     const [type, schemas] = alternatives;
-    return flattenAlternatives(type, schemas, new Set(ancestors).add(schema));
+    return mergeAlternatives(
+        type,
+        flattenAlternatives(type, schemas, new Set(ancestors).add(schema))
+    );
+}
+
+/**
+ * Merge alternatives of the same type into a single schema.
+ * - Merge string enums
+ */
+function mergeAlternatives(
+    alternativeType: AlternativeType,
+    schemasOrRefs: OpenAPIV3.SchemaObject[]
+): OpenAPIV3.SchemaObject[] | null {
+    switch (alternativeType) {
+        case 'oneOf': {
+            return schemasOrRefs.reduce<OpenAPIV3.SchemaObject[]>((acc, schemaOrRef) => {
+                const latest = acc.at(-1);
+
+                if (
+                    latest &&
+                    latest.type === 'string' &&
+                    latest.enum &&
+                    schemaOrRef.type === 'string' &&
+                    schemaOrRef.enum
+                ) {
+                    latest.enum = Array.from(new Set([...latest.enum, ...schemaOrRef.enum]));
+                    latest.nullable = latest.nullable || schemaOrRef.nullable;
+                    return acc;
+                }
+
+                acc.push(schemaOrRef);
+                return acc;
+            }, []);
+        }
+        case 'allOf': {
+            return schemasOrRefs.reduce<OpenAPIV3.SchemaObject[]>((acc, schemaOrRef) => {
+                const latest = acc.at(-1);
+
+                if (
+                    latest &&
+                    latest.type === 'string' &&
+                    latest.enum &&
+                    schemaOrRef.type === 'string' &&
+                    schemaOrRef.enum
+                ) {
+                    const keys = Object.keys(schemaOrRef);
+                    if (keys.every((key) => ['type', 'enum', 'nullable'].includes(key))) {
+                        latest.enum = Array.from(new Set([...latest.enum, ...schemaOrRef.enum]));
+                        latest.nullable = latest.nullable || schemaOrRef.nullable;
+                        return acc;
+                    }
+                }
+
+                if (latest && latest.type === 'object' && schemaOrRef.type === 'object') {
+                    const keys = Object.keys(schemaOrRef);
+                    if (
+                        keys.every((key) =>
+                            ['type', 'properties', 'required', 'nullable'].includes(key)
+                        )
+                    ) {
+                        latest.properties = {
+                            ...latest.properties,
+                            ...schemaOrRef.properties,
+                        };
+                        latest.required = Array.from(
+                            new Set([
+                                ...(Array.isArray(latest.required) ? latest.required : []),
+                                ...(Array.isArray(schemaOrRef.required)
+                                    ? schemaOrRef.required
+                                    : []),
+                            ])
+                        );
+                        latest.nullable = latest.nullable || schemaOrRef.nullable;
+                        return acc;
+                    }
+                }
+
+                acc.push(schemaOrRef);
+                return acc;
+            }, []);
+        }
+        default:
+            return schemasOrRefs;
+    }
 }
 
 function flattenAlternatives(
@@ -485,19 +602,26 @@ function getSchemaTitle(schema: OpenAPIV3.SchemaObject): string {
     return type;
 }
 
-function getDisclosureLabel(schema: OpenAPIV3.SchemaObject): string {
+function getDisclosureLabel(props: {
+    schema: OpenAPIV3.SchemaObject;
+    isExpanded: boolean;
+    context: OpenAPIClientContext;
+}) {
+    const { schema, isExpanded, context } = props;
+    let label: string;
     if (schema.type === 'array' && !!schema.items) {
         if (schema.items.oneOf) {
-            return 'available items';
+            label = tString(context.translation, 'available_items').toLowerCase();
         }
-
         // Fallback to "child attributes" for enums and objects
-        if (schema.items.enum || schema.items.type === 'object') {
-            return 'child attributes';
+        else if (schema.items.enum || schema.items.type === 'object') {
+            label = tString(context.translation, 'child_attributes').toLowerCase();
+        } else {
+            label = schema.items.title ?? schema.title ?? getSchemaTitle(schema.items);
         }
-
-        return schema.items.title ?? schema.title ?? getSchemaTitle(schema.items);
+    } else {
+        label = schema.title || tString(context.translation, 'child_attributes').toLowerCase();
     }
 
-    return schema.title || 'child attributes';
+    return `${isExpanded ? tString(context.translation, 'hide') : tString(context.translation, 'show')} ${label}`;
 }

package/src/OpenAPISchemaName.tsx

@@ -1,12 +1,14 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import type React from 'react';
-import { stringifyOpenAPI } from './stringifyOpenAPI';
+import type { OpenAPIClientContext } from './context';
+import { t, tString } from './translate';
 
 interface OpenAPISchemaNameProps {
     schema?: OpenAPIV3.SchemaObject;
     propertyName?: string | React.JSX.Element;
     required?: boolean;
     type?: string;
+    context: OpenAPIClientContext;
 }
 
 /**
@@ -14,12 +16,12 @@ interface OpenAPISchemaNameProps {
  * It includes the property name, type, required and deprecated status.
  */
 export function OpenAPISchemaName(props: OpenAPISchemaNameProps) {
-    const { schema, type, propertyName, required } = props;
+    const { schema, type, propertyName, required, context } = props;
 
-    const additionalItems = schema && getAdditionalItems(schema);
+    const additionalItems = schema && getAdditionalItems(schema, context);
 
     return (
-        <div className="openapi-schema-name">
+        <span className="openapi-schema-name">
             {propertyName ? (
                 <span data-deprecated={schema?.deprecated} className="openapi-schema-propertyname">
                     {propertyName}
@@ -31,38 +33,45 @@ export function OpenAPISchemaName(props: OpenAPISchemaNameProps) {
                     <span className="openapi-schema-type">{additionalItems}</span>
                 ) : null}
             </span>
-            {schema?.readOnly ? <span className="openapi-schema-readonly">read-only</span> : null}
+            {schema?.readOnly ? (
+                <span className="openapi-schema-readonly">
+                    {t(context.translation, 'read_only')}
+                </span>
+            ) : null}
             {schema?.writeOnly ? (
-                <span className="openapi-schema-writeonly">write-only</span>
+                <span className="openapi-schema-writeonly">
+                    {t(context.translation, 'write_only')}
+                </span>
             ) : null}
             {required ? (
-                <span className="openapi-schema-required">required</span>
+                <span className="openapi-schema-required">
+                    {t(context.translation, 'required')}
+                </span>
             ) : (
-                <span className="openapi-schema-optional">optional</span>
+                <span className="openapi-schema-optional">
+                    {t(context.translation, 'optional')}
+                </span>
             )}
-            {schema?.deprecated ? <span className="openapi-deprecated">Deprecated</span> : null}
-        </div>
+            {schema?.deprecated ? (
+                <span className="openapi-deprecated">{t(context.translation, 'deprecated')}</span>
+            ) : null}
+        </span>
     );
 }
 
-function getAdditionalItems(schema: OpenAPIV3.SchemaObject): string {
+function getAdditionalItems(schema: OpenAPIV3.SchemaObject, context: OpenAPIClientContext): string {
     let additionalItems = '';
 
     if (schema.minimum || schema.minLength || schema.minItems) {
-        additionalItems += ` · min: ${schema.minimum || schema.minLength || schema.minItems}`;
+        additionalItems += ` · ${tString(context.translation, 'min').toLowerCase()}: ${schema.minimum || schema.minLength || schema.minItems}`;
     }
 
     if (schema.maximum || schema.maxLength || schema.maxItems) {
-        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)}`;
+        additionalItems += ` · ${tString(context.translation, 'max').toLowerCase()}: ${schema.maximum || schema.maxLength || schema.maxItems}`;
     }
 
     if (schema.nullable) {
-        additionalItems = ' | nullable';
+        additionalItems = ` | ${tString(context.translation, 'nullable').toLowerCase()}`;
     }
 
     return additionalItems;

package/src/OpenAPISchemaServer.tsx

@@ -4,8 +4,8 @@ import {
     OpenAPISchemaPropertiesFromServer,
     type OpenAPISchemaPropertyEntry,
 } from './OpenAPISchema';
+import type { OpenAPIClientContext } from './context';
 import { decycle } from './decycle';
-import type { OpenAPIClientContext } from './types';
 
 export function OpenAPISchemaProperties(props: {
     id?: string;

package/src/OpenAPISecurities.tsx

@@ -1,9 +1,10 @@
-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 { resolveDescription } from './utils';
+import type { OpenAPIClientContext } from './context';
+import { t } from './translate';
+import type { OpenAPIOperationData, OpenAPISecurityWithRequired } from './types';
+import { createStateKey, resolveDescription } from './utils';
 
 /**
  * Present securities authorization that can be used for this operation.
@@ -20,10 +21,12 @@ export function OpenAPISecurities(props: {
 
     return (
         <InteractiveSection
-            header="Authorizations"
+            header={t(context.translation, 'authorizations')}
+            stateKey={createStateKey('securities', context.blockKey)}
             toggeable
             defaultOpened={false}
             toggleIcon={context.icons.chevronRight}
+            selectIcon={context.icons.chevronDown}
             className="openapi-securities"
             tabs={securities.map(([key, security]) => {
                 const description = resolveDescription(security);
@@ -33,7 +36,7 @@ export function OpenAPISecurities(props: {
                     body: (
                         <div className="openapi-schema">
                             <div className="openapi-schema-presentation">
-                                {getLabelForType(security)}
+                                {getLabelForType(security, context)}
 
                                 {description ? (
                                     <Markdown
@@ -50,26 +53,39 @@ export function OpenAPISecurities(props: {
     );
 }
 
-function getLabelForType(security: OpenAPIV3_1.SecuritySchemeObject) {
+function getLabelForType(security: OpenAPISecurityWithRequired, context: OpenAPIClientContext) {
     switch (security.type) {
         case 'apiKey':
             return (
                 <OpenAPISchemaName
+                    context={context}
                     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
+                        context={context}
+                        propertyName="Authorization"
+                        type="string"
+                        required={security.required}
+                    />
+                );
             }
 
             if (security.scheme === 'bearer') {
                 const description = resolveDescription(security);
                 return (
                     <>
-                        <OpenAPISchemaName propertyName="Authorization" type="string" required />
+                        <OpenAPISchemaName
+                            context={context}
+                            propertyName="Authorization"
+                            type="string"
+                            required={security.required}
+                        />
                         {/** Show a default description if none is provided */}
                         {!description ? (
                             <Markdown
@@ -81,11 +97,29 @@ function getLabelForType(security: OpenAPIV3_1.SecuritySchemeObject) {
                 );
             }
 
-            return <OpenAPISchemaName propertyName="HTTP" required />;
+            return (
+                <OpenAPISchemaName
+                    context={context}
+                    propertyName="HTTP"
+                    required={security.required}
+                />
+            );
         case 'oauth2':
-            return <OpenAPISchemaName propertyName="OAuth2" required />;
+            return (
+                <OpenAPISchemaName
+                    context={context}
+                    propertyName="OAuth2"
+                    required={security.required}
+                />
+            );
         case 'openIdConnect':
-            return <OpenAPISchemaName propertyName="OpenID Connect" required />;
+            return (
+                <OpenAPISchemaName
+                    context={context}
+                    propertyName="OpenID Connect"
+                    required={security.required}
+                />
+            );
         default:
             // @ts-ignore
             return security.type;

package/src/OpenAPISelect.tsx

@@ -0,0 +1,96 @@
+'use client';
+
+import clsx from 'clsx';
+import { useCallback } from 'react';
+import {
+    Button,
+    type Key,
+    ListBox,
+    ListBoxItem,
+    type ListBoxItemProps,
+    Popover,
+    type PopoverProps,
+    Select,
+    type SelectProps,
+    SelectValue,
+} from 'react-aria-components';
+import { useStore } from 'zustand';
+import { getOrCreateStoreByKey } from './getOrCreateStoreByKey';
+
+export type OpenAPISelectItem = {
+    key: Key;
+    label: string | React.ReactNode;
+};
+
+interface OpenAPISelectProps<T extends OpenAPISelectItem> extends Omit<SelectProps<T>, 'children'> {
+    items: T[];
+    children: React.ReactNode | ((item: T) => React.ReactNode);
+    placement?: PopoverProps['placement'];
+    stateKey?: string;
+    /**
+     * Icon to display in the select button.
+     */
+    icon?: React.ReactNode;
+}
+
+export function useSelectState(stateKey = 'select-state', initialKey?: Key) {
+    const store = useStore(getOrCreateStoreByKey(stateKey, initialKey));
+    return {
+        key: store.key,
+        setKey: useCallback((key: Key | null) => store.setKey(key), [store.setKey]),
+    };
+}
+
+export function OpenAPISelect<T extends OpenAPISelectItem>(props: OpenAPISelectProps<T>) {
+    const {
+        icon = '▼',
+        items,
+        children,
+        className,
+        placement,
+        stateKey,
+        selectedKey,
+        onSelectionChange,
+    } = props;
+
+    const state = useSelectState(stateKey, items[0]?.key);
+
+    const selected = items.find((item) => item.key === state.key) || items[0];
+
+    return (
+        <Select
+            aria-label="OpenAPI Select"
+            {...props}
+            selectedKey={selectedKey || selected?.key}
+            onSelectionChange={(key) => {
+                onSelectionChange?.(key);
+                state.setKey(key);
+            }}
+            className={clsx('openapi-select', className)}
+        >
+            <Button>
+                <SelectValue />
+                {icon}
+            </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,
+                })
+            }
+        />
+    );
+}