@gitbook/react-openapi 1.1.10 → 1.2.1

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,9 +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 { stringifyOpenAPI } from './stringifyOpenAPI';
-import type { OpenAPIClientContext } from './types';
+import { tString } from './translate';
 import { checkIsReference, resolveDescription, resolveFirstExample } from './utils';
 
 type CircularRefsIds = Map<OpenAPIV3.SchemaObject, string>;
@@ -40,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
@@ -54,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}
@@ -208,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}
@@ -246,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
@@ -290,6 +300,7 @@ function OpenAPISchemaEnum(props: {
                         value={item.value}
                         label={item.description}
                         withTooltip={!!item.description}
+                        context={context}
                     >
                         <code>{`${item.value}`}</code>
                     </OpenAPICopyButton>
@@ -302,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);
@@ -317,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">
@@ -349,7 +365,7 @@ function OpenAPISchemaPresentation(props: { property: OpenAPISchemaPropertyEntry
                     Pattern: <code>{schema.pattern}</code>
                 </span>
             ) : null}
-            <OpenAPISchemaEnum schema={schema} />
+            <OpenAPISchemaEnum schema={schema} context={context} />
         </div>
     );
 }
@@ -444,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(
@@ -502,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,11 +1,14 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import type React from 'react';
+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;
 }
 
 /**
@@ -13,9 +16,9 @@ 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 (
         <span className="openapi-schema-name">
@@ -30,33 +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}
+            {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}`;
+        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,12 +1,10 @@
 import { InteractiveSection } from './InteractiveSection';
 import { Markdown } from './Markdown';
 import { OpenAPISchemaName } from './OpenAPISchemaName';
-import type {
-    OpenAPIClientContext,
-    OpenAPIOperationData,
-    OpenAPISecurityWithRequired,
-} 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.
@@ -23,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);
@@ -36,7 +36,7 @@ export function OpenAPISecurities(props: {
                     body: (
                         <div className="openapi-schema">
                             <div className="openapi-schema-presentation">
-                                {getLabelForType(security)}
+                                {getLabelForType(security, context)}
 
                                 {description ? (
                                     <Markdown
@@ -53,11 +53,12 @@ export function OpenAPISecurities(props: {
     );
 }
 
-function getLabelForType(security: OpenAPISecurityWithRequired) {
+function getLabelForType(security: OpenAPISecurityWithRequired, context: OpenAPIClientContext) {
     switch (security.type) {
         case 'apiKey':
             return (
                 <OpenAPISchemaName
+                    context={context}
                     propertyName={security.name ?? 'apiKey'}
                     type="string"
                     required={security.required}
@@ -67,6 +68,7 @@ function getLabelForType(security: OpenAPISecurityWithRequired) {
             if (security.scheme === 'basic') {
                 return (
                     <OpenAPISchemaName
+                        context={context}
                         propertyName="Authorization"
                         type="string"
                         required={security.required}
@@ -79,6 +81,7 @@ function getLabelForType(security: OpenAPISecurityWithRequired) {
                 return (
                     <>
                         <OpenAPISchemaName
+                            context={context}
                             propertyName="Authorization"
                             type="string"
                             required={security.required}
@@ -94,11 +97,29 @@ function getLabelForType(security: OpenAPISecurityWithRequired) {
                 );
             }
 
-            return <OpenAPISchemaName propertyName="HTTP" required={security.required} />;
+            return (
+                <OpenAPISchemaName
+                    context={context}
+                    propertyName="HTTP"
+                    required={security.required}
+                />
+            );
         case 'oauth2':
-            return <OpenAPISchemaName propertyName="OAuth2" required={security.required} />;
+            return (
+                <OpenAPISchemaName
+                    context={context}
+                    propertyName="OAuth2"
+                    required={security.required}
+                />
+            );
         case 'openIdConnect':
-            return <OpenAPISchemaName propertyName="OpenID Connect" required={security.required} />;
+            return (
+                <OpenAPISchemaName
+                    context={context}
+                    propertyName="OpenID Connect"
+                    required={security.required}
+                />
+            );
         default:
             // @ts-ignore
             return security.type;

package/src/OpenAPISelect.tsx

@@ -1,6 +1,7 @@
 'use client';
 
 import clsx from 'clsx';
+import { useCallback } from 'react';
 import {
     Button,
     type Key,
@@ -13,38 +14,63 @@ import {
     type SelectProps,
     SelectValue,
 } from 'react-aria-components';
+import { useStore } from 'zustand';
+import { getOrCreateStoreByKey } from './getOrCreateStoreByKey';
 
 export type OpenAPISelectItem = {
     key: Key;
-    label: string;
+    label: string | React.ReactNode;
 };
 
 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'];
+    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 { items, children, className, placement } = props;
+    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 {...props} className={clsx('openapi-select', className)}>
+        <Select
+            aria-label="OpenAPI Select"
+            {...props}
+            selectedKey={selectedKey || selected?.key}
+            onSelectionChange={(key) => {
+                onSelectionChange?.(key);
+                state.setKey(key);
+            }}
+            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>
+                {icon}
             </Button>
             <Popover placement={placement} className="openapi-select-popover">
                 <ListBox className="openapi-select-listbox" items={items}>

package/src/OpenAPISpec.tsx

@@ -5,16 +5,23 @@ import { OpenAPIResponses } from './OpenAPIResponses';
 import { OpenAPISchemaProperties } from './OpenAPISchemaServer';
 import { OpenAPISecurities } from './OpenAPISecurities';
 import { StaticSection } from './StaticSection';
-import type { OpenAPIClientContext, OpenAPIOperationData } from './types';
+import type { OpenAPIClientContext } from './context';
+import { tString } from './translate';
+import type { OpenAPIOperationData, OpenAPIWebhookData } from './types';
 import { parameterToProperty } from './utils';
 
-export function OpenAPISpec(props: { data: OpenAPIOperationData; context: OpenAPIClientContext }) {
+export function OpenAPISpec(props: {
+    data: OpenAPIOperationData | OpenAPIWebhookData;
+    context: OpenAPIClientContext;
+}) {
     const { data, context } = props;
 
-    const { operation, securities } = data;
+    const { operation } = data;
 
     const parameters = operation.parameters ?? [];
-    const parameterGroups = groupParameters(parameters);
+    const parameterGroups = groupParameters(parameters, context);
+
+    const securities = 'securities' in data ? data.securities : [];
 
     return (
         <>
@@ -42,6 +49,7 @@ export function OpenAPISpec(props: { data: OpenAPIOperationData; context: OpenAP
                     key="body"
                     requestBody={operation.requestBody}
                     context={context}
+                    data={data}
                 />
             ) : null}
             {operation.responses ? (
@@ -55,7 +63,10 @@ export function OpenAPISpec(props: { data: OpenAPIOperationData; context: OpenAP
     );
 }
 
-function groupParameters(parameters: OpenAPI.Parameters): Array<{
+function groupParameters(
+    parameters: OpenAPI.Parameters,
+    context: OpenAPIClientContext
+): Array<{
     key: string;
     label: string;
     parameters: OpenAPI.Parameters;
@@ -72,7 +83,7 @@ function groupParameters(parameters: OpenAPI.Parameters): Array<{
         .filter((parameter) => parameter.in)
         .forEach((parameter) => {
             const key = parameter.in;
-            const label = getParameterGroupName(parameter.in);
+            const label = getParameterGroupName(parameter.in, context);
             const group = groups.find((group) => group.key === key);
             if (group) {
                 group.parameters.push(parameter);
@@ -90,14 +101,14 @@ function groupParameters(parameters: OpenAPI.Parameters): Array<{
     return groups;
 }
 
-function getParameterGroupName(paramIn: string): string {
+function getParameterGroupName(paramIn: string, context: OpenAPIClientContext): string {
     switch (paramIn) {
         case 'path':
-            return 'Path parameters';
+            return tString(context.translation, 'path_parameters');
         case 'query':
-            return 'Query parameters';
+            return tString(context.translation, 'query_parameters');
         case 'header':
-            return 'Header parameters';
+            return tString(context.translation, 'header_parameters');
         default:
             return paramIn;
     }