@gitbook/react-openapi 1.2.1 → 1.3.1

package/src/OpenAPISchema.tsx

@@ -4,6 +4,7 @@
 
 import type { OpenAPICustomOperationProperties, OpenAPIV3 } from '@gitbook/openapi-parser';
 import { useId } from 'react';
+import type { ComponentPropsWithoutRef } from 'react';
 
 import clsx from 'clsx';
 import { Markdown } from './Markdown';
@@ -12,80 +13,105 @@ import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 import { OpenAPISchemaName } from './OpenAPISchemaName';
 import type { OpenAPIClientContext } from './context';
 import { retrocycle } from './decycle';
+import { getDisclosureLabel } from './getDisclosureLabel';
 import { stringifyOpenAPI } from './stringifyOpenAPI';
 import { tString } from './translate';
-import { checkIsReference, resolveDescription, resolveFirstExample } from './utils';
+import { checkIsReference, getSchemaTitle, resolveDescription, resolveFirstExample } from './utils';
 
 type CircularRefsIds = Map<OpenAPIV3.SchemaObject, string>;
 
 export interface OpenAPISchemaPropertyEntry {
-    propertyName?: string | undefined;
-    required?: boolean | undefined;
+    propertyName?: string;
+    required?: boolean | null;
     schema: OpenAPIV3.SchemaObject;
 }
 
 /**
  * Render a property of an OpenAPI schema.
  */
-function OpenAPISchemaProperty(props: {
-    property: OpenAPISchemaPropertyEntry;
-    context: OpenAPIClientContext;
-    circularRefs: CircularRefsIds;
-    className?: string;
-}) {
-    const { circularRefs: parentCircularRefs, context, className, property } = props;
+function OpenAPISchemaProperty(
+    props: {
+        property: OpenAPISchemaPropertyEntry;
+        context: OpenAPIClientContext;
+        circularRefs: CircularRefsIds;
+        className?: string;
+    } & Omit<ComponentPropsWithoutRef<'div'>, 'property' | 'context' | 'circularRefs' | 'className'>
+) {
+    const { circularRefs: parentCircularRefs, context, className, property, ...rest } = props;
 
     const { schema } = property;
 
     const id = useId();
 
-    return (
-        <div id={id} className={clsx('openapi-schema', className)}>
-            <OpenAPISchemaPresentation context={context} property={property} />
-            {(() => {
-                const circularRefId = parentCircularRefs.get(schema);
-                // Avoid recursing infinitely, and instead render a link to the parent schema
-                if (circularRefId) {
-                    return <OpenAPISchemaCircularRef id={circularRefId} schema={schema} />;
-                }
+    const circularRefId = parentCircularRefs.get(schema);
+    // Avoid recursing infinitely, and instead render a link to the parent schema
+    if (circularRefId) {
+        return <OpenAPISchemaCircularRef id={circularRefId} schema={schema} />;
+    }
+
+    const circularRefs = new Map(parentCircularRefs);
+    circularRefs.set(schema, id);
+
+    const properties = getSchemaProperties(schema);
+
+    const ancestors = new Set(circularRefs.keys());
+    const alternatives = getSchemaAlternatives(schema, ancestors);
 
-                const circularRefs = new Map(parentCircularRefs);
-                circularRefs.set(schema, id);
-
-                const properties = getSchemaProperties(schema);
-                if (properties?.length) {
-                    return (
-                        <OpenAPIDisclosure
-                            icon={context.icons.plus}
-                            label={(isExpanded) =>
-                                getDisclosureLabel({ schema, isExpanded, context })
-                            }
-                        >
-                            <OpenAPISchemaProperties
-                                properties={properties}
+    const header = <OpenAPISchemaPresentation context={context} property={property} />;
+    const content = (() => {
+        if (properties?.length) {
+            return (
+                <OpenAPISchemaProperties
+                    properties={properties}
+                    circularRefs={circularRefs}
+                    context={context}
+                />
+            );
+        }
+
+        if (alternatives) {
+            return (
+                <div className="openapi-schema-alternatives">
+                    {alternatives.map((alternativeSchema, index) => (
+                        <div key={index} className="openapi-schema-alternative">
+                            <OpenAPISchemaAlternative
+                                schema={alternativeSchema}
                                 circularRefs={circularRefs}
                                 context={context}
                             />
-                        </OpenAPIDisclosure>
-                    );
-                }
+                            {index < alternatives.length - 1 ? (
+                                <OpenAPISchemaAlternativeSeparator
+                                    schema={schema}
+                                    context={context}
+                                />
+                            ) : null}
+                        </div>
+                    ))}
+                </div>
+            );
+        }
 
-                const ancestors = new Set(circularRefs.keys());
-                const alternatives = getSchemaAlternatives(schema, ancestors);
-
-                if (alternatives) {
-                    return alternatives.map((schema, index) => (
-                        <OpenAPISchemaAlternative
-                            key={index}
-                            schema={schema}
-                            circularRefs={circularRefs}
-                            context={context}
-                        />
-                    ));
-                }
+        return null;
+    })();
+
+    if (properties?.length) {
+        return (
+            <OpenAPIDisclosure
+                icon={context.icons.plus}
+                className={clsx('openapi-schema', className)}
+                header={header}
+                label={(isExpanded) => getDisclosureLabel({ schema, isExpanded, context })}
+                {...rest}
+            >
+                {content}
+            </OpenAPIDisclosure>
+        );
+    }
 
-                return null;
-            })()}
+    return (
+        <div id={id} {...rest} className={clsx('openapi-schema', className)}>
+            {header}
+            {content}
         </div>
     );
 }
@@ -115,6 +141,7 @@ function OpenAPISchemaProperties(props: {
                         circularRefs={circularRefs}
                         property={property}
                         context={context}
+                        style={{ animationDelay: `${index * 0.02}s` }}
                     />
                 );
             })}
@@ -205,34 +232,48 @@ function OpenAPISchemaAlternative(props: {
     context: OpenAPIClientContext;
 }) {
     const { schema, circularRefs, context } = props;
-
-    const description = resolveDescription(schema);
     const properties = getSchemaProperties(schema);
 
+    return properties?.length ? (
+        <OpenAPIDisclosure
+            icon={context.icons.plus}
+            header={<OpenAPISchemaPresentation property={{ schema }} context={context} />}
+            label={(isExpanded) => getDisclosureLabel({ schema, isExpanded, context })}
+        >
+            <OpenAPISchemaProperties
+                properties={properties}
+                circularRefs={circularRefs}
+                context={context}
+            />
+        </OpenAPIDisclosure>
+    ) : (
+        <OpenAPISchemaProperty
+            property={{ schema }}
+            circularRefs={circularRefs}
+            context={context}
+        />
+    );
+}
+
+function OpenAPISchemaAlternativeSeparator(props: {
+    schema: OpenAPIV3.SchemaObject;
+    context: OpenAPIClientContext;
+}) {
+    const { schema, context } = props;
+
+    const anyOf = schema.anyOf || schema.items?.anyOf;
+    const oneOf = schema.oneOf || schema.items?.oneOf;
+    const allOf = schema.allOf || schema.items?.allOf;
+
+    if (!anyOf && !oneOf && !allOf) {
+        return null;
+    }
+
     return (
-        <>
-            {description ? (
-                <Markdown source={description} className="openapi-schema-description" />
-            ) : null}
-            <OpenAPIDisclosure
-                icon={context.icons.plus}
-                label={(isExpanded) => getDisclosureLabel({ schema, isExpanded, context })}
-            >
-                {properties?.length ? (
-                    <OpenAPISchemaProperties
-                        properties={properties}
-                        circularRefs={circularRefs}
-                        context={context}
-                    />
-                ) : (
-                    <OpenAPISchemaProperty
-                        property={{ schema }}
-                        circularRefs={circularRefs}
-                        context={context}
-                    />
-                )}
-            </OpenAPIDisclosure>
-        </>
+        <span className="openapi-schema-alternative-separator">
+            {(anyOf || oneOf) && tString(context.translation, 'or')}
+            {allOf && tString(context.translation, 'and')}
+        </span>
     );
 }
 
@@ -293,7 +334,7 @@ function OpenAPISchemaEnum(props: {
 
     return (
         <span className="openapi-schema-enum">
-            Available options:{' '}
+            {tString(context.translation, 'possible_values')}:{' '}
             {enumValues.map((item, index) => (
                 <span key={index} className="openapi-schema-enum-value">
                     <OpenAPICopyButton
@@ -313,7 +354,7 @@ function OpenAPISchemaEnum(props: {
 /**
  * Render the top row of a schema. e.g: name, type, and required status.
  */
-function OpenAPISchemaPresentation(props: {
+export function OpenAPISchemaPresentation(props: {
     property: OpenAPISchemaPropertyEntry;
     context: OpenAPIClientContext;
 }) {
@@ -437,6 +478,14 @@ export function getSchemaAlternatives(
     schema: OpenAPIV3.SchemaObject,
     ancestors: Set<OpenAPIV3.SchemaObject> = new Set()
 ): OpenAPIV3.SchemaObject[] | null {
+    // Search for alternatives in the items property if it exists
+    if (
+        schema.items &&
+        ('oneOf' in schema.items || 'allOf' in schema.items || 'anyOf' in schema.items)
+    ) {
+        return getSchemaAlternatives(schema.items, ancestors);
+    }
+
     const alternatives:
         | [AlternativeType, (OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject)[]]
         | null = (() => {
@@ -552,6 +601,9 @@ function flattenAlternatives(
     schemasOrRefs: (OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject)[],
     ancestors: Set<OpenAPIV3.SchemaObject>
 ): OpenAPIV3.SchemaObject[] {
+    // Get the parent schema's required fields from the most recent ancestor
+    const latestAncestor = Array.from(ancestors).pop();
+
     return schemasOrRefs.reduce<OpenAPIV3.SchemaObject[]>((acc, schemaOrRef) => {
         if (checkIsReference(schemaOrRef)) {
             return acc;
@@ -560,68 +612,43 @@ function flattenAlternatives(
         if (schemaOrRef[alternativeType] && !ancestors.has(schemaOrRef)) {
             const schemas = getSchemaAlternatives(schemaOrRef, ancestors);
             if (schemas) {
-                acc.push(...schemas);
+                acc.push(
+                    ...schemas.map((schema) => ({
+                        ...schema,
+                        required: mergeRequiredFields(schema, latestAncestor),
+                    }))
+                );
             }
             return acc;
         }
 
-        acc.push(schemaOrRef);
+        // For direct schemas, handle required fields
+        const schema = {
+            ...schemaOrRef,
+            required: mergeRequiredFields(schemaOrRef, latestAncestor),
+        };
+
+        acc.push(schema);
         return acc;
     }, []);
 }
 
-function getSchemaTitle(schema: OpenAPIV3.SchemaObject): string {
-    // Otherwise try to infer a nice title
-    let type = 'any';
-
-    if (schema.enum || schema['x-enumDescriptions'] || schema['x-gitbook-enum']) {
-        type = `${schema.type} · enum`;
-        // check array AND schema.items as this is sometimes null despite what the type indicates
-    } else if (schema.type === 'array' && !!schema.items) {
-        type = `${getSchemaTitle(schema.items)}[]`;
-    } else if (Array.isArray(schema.type)) {
-        type = schema.type.join(' | ');
-    } else if (schema.type || schema.properties) {
-        type = schema.type ?? 'object';
-
-        if (schema.format) {
-            type += ` · ${schema.format}`;
-        }
-    }
-
-    if ('anyOf' in schema) {
-        type = 'any of';
-    } else if ('oneOf' in schema) {
-        type = 'one of';
-    } else if ('allOf' in schema) {
-        type = 'all of';
-    } else if ('not' in schema) {
-        type = 'not';
+/**
+ * Merge the required fields of a schema with the required fields of its latest ancestor.
+ */
+function mergeRequiredFields(
+    schemaOrRef: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject,
+    latestAncestor: OpenAPIV3.SchemaObject | undefined
+) {
+    if (!schemaOrRef.required && !latestAncestor?.required) {
+        return undefined;
     }
 
-    return type;
-}
-
-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) {
-            label = tString(context.translation, 'available_items').toLowerCase();
-        }
-        // Fallback to "child attributes" for enums and objects
-        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);
-        }
-    } else {
-        label = schema.title || tString(context.translation, 'child_attributes').toLowerCase();
+    if (checkIsReference(schemaOrRef)) {
+        return latestAncestor?.required;
     }
 
-    return `${isExpanded ? tString(context.translation, 'hide') : tString(context.translation, 'show')} ${label}`;
+    return Array.from(
+        new Set([...(latestAncestor?.required || []), ...(schemaOrRef.required || [])])
+    );
 }

package/src/OpenAPISchemaName.tsx

@@ -6,7 +6,7 @@ import { t, tString } from './translate';
 interface OpenAPISchemaNameProps {
     schema?: OpenAPIV3.SchemaObject;
     propertyName?: string | React.JSX.Element;
-    required?: boolean;
+    required?: boolean | null;
     type?: string;
     context: OpenAPIClientContext;
 }
@@ -27,12 +27,14 @@ export function OpenAPISchemaName(props: OpenAPISchemaNameProps) {
                     {propertyName}
                 </span>
             ) : null}
-            <span>
-                {type ? <span className="openapi-schema-type">{type}</span> : null}
-                {additionalItems ? (
-                    <span className="openapi-schema-type">{additionalItems}</span>
-                ) : null}
-            </span>
+            {type || additionalItems ? (
+                <span>
+                    {type ? <span className="openapi-schema-type">{type}</span> : null}
+                    {additionalItems ? (
+                        <span className="openapi-schema-type">{additionalItems}</span>
+                    ) : null}
+                </span>
+            ) : null}
             {schema?.readOnly ? (
                 <span className="openapi-schema-readonly">
                     {t(context.translation, 'read_only')}
@@ -43,7 +45,7 @@ export function OpenAPISchemaName(props: OpenAPISchemaNameProps) {
                     {t(context.translation, 'write_only')}
                 </span>
             ) : null}
-            {required ? (
+            {required === null ? null : required ? (
                 <span className="openapi-schema-required">
                     {t(context.translation, 'required')}
                 </span>

package/src/OpenAPISecurities.tsx

@@ -1,5 +1,7 @@
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import { InteractiveSection } from './InteractiveSection';
 import { Markdown } from './Markdown';
+import { OpenAPICopyButton } from './OpenAPICopyButton';
 import { OpenAPISchemaName } from './OpenAPISchemaName';
 import type { OpenAPIClientContext } from './context';
 import { t } from './translate';
@@ -105,13 +107,7 @@ function getLabelForType(security: OpenAPISecurityWithRequired, context: OpenAPI
                 />
             );
         case 'oauth2':
-            return (
-                <OpenAPISchemaName
-                    context={context}
-                    propertyName="OAuth2"
-                    required={security.required}
-                />
-            );
+            return <OpenAPISchemaOAuth2Flows context={context} security={security} />;
         case 'openIdConnect':
             return (
                 <OpenAPISchemaName
@@ -125,3 +121,111 @@ function getLabelForType(security: OpenAPISecurityWithRequired, context: OpenAPI
             return security.type;
     }
 }
+
+function OpenAPISchemaOAuth2Flows(props: {
+    context: OpenAPIClientContext;
+    security: OpenAPIV3.OAuth2SecurityScheme & { required?: boolean };
+}) {
+    const { context, security } = props;
+
+    const flows = Object.entries(security.flows ?? {});
+
+    return (
+        <div className="openapi-securities-oauth-flows">
+            {flows.map(([name, flow], index) => (
+                <OpenAPISchemaOAuth2Item
+                    key={index}
+                    flow={flow}
+                    name={name}
+                    context={context}
+                    security={security}
+                />
+            ))}
+        </div>
+    );
+}
+
+function OpenAPISchemaOAuth2Item(props: {
+    flow: NonNullable<OpenAPIV3.OAuth2SecurityScheme['flows']>[keyof NonNullable<
+        OpenAPIV3.OAuth2SecurityScheme['flows']
+    >];
+    name: string;
+    context: OpenAPIClientContext;
+    security: OpenAPIV3.OAuth2SecurityScheme & { required?: boolean };
+}) {
+    const { flow, context, security, name } = props;
+
+    if (!flow) {
+        return null;
+    }
+
+    const scopes = Object.entries(flow?.scopes ?? {});
+
+    return (
+        <div>
+            <OpenAPISchemaName
+                context={context}
+                propertyName="OAuth2"
+                type={name}
+                required={security.required}
+            />
+            <div className="openapi-securities-oauth-content openapi-markdown">
+                {security.description ? <Markdown source={security.description} /> : null}
+                {'authorizationUrl' in flow && flow.authorizationUrl ? (
+                    <span>
+                        Authorization URL:{' '}
+                        <OpenAPICopyButton
+                            value={flow.authorizationUrl}
+                            context={context}
+                            className="openapi-securities-url"
+                            withTooltip
+                        >
+                            {flow.authorizationUrl}
+                        </OpenAPICopyButton>
+                    </span>
+                ) : null}
+                {'tokenUrl' in flow && flow.tokenUrl ? (
+                    <span>
+                        Token URL:{' '}
+                        <OpenAPICopyButton
+                            value={flow.tokenUrl}
+                            context={context}
+                            className="openapi-securities-url"
+                            withTooltip
+                        >
+                            {flow.tokenUrl}
+                        </OpenAPICopyButton>
+                    </span>
+                ) : null}
+                {'refreshUrl' in flow && flow.refreshUrl ? (
+                    <span>
+                        Refresh URL:{' '}
+                        <OpenAPICopyButton
+                            value={flow.refreshUrl}
+                            context={context}
+                            className="openapi-securities-url"
+                            withTooltip
+                        >
+                            {flow.refreshUrl}
+                        </OpenAPICopyButton>
+                    </span>
+                ) : null}
+                {scopes.length ? (
+                    <div>
+                        {t(context.translation, 'available_scopes')}:{' '}
+                        <ul>
+                            {scopes.map(([key, value]) => (
+                                <li key={key}>
+                                    <OpenAPICopyButton value={key} context={context} withTooltip>
+                                        <code>{key}</code>
+                                    </OpenAPICopyButton>
+                                    : {value}
+                                </li>
+                            ))}
+                        </ul>
+                    </div>
+                ) : null}
+            </div>
+        </div>
+    );
+}

package/src/OpenAPISelect.tsx

@@ -33,7 +33,7 @@ interface OpenAPISelectProps<T extends OpenAPISelectItem> extends Omit<SelectPro
     icon?: React.ReactNode;
 }
 
-export function useSelectState(stateKey = 'select-state', initialKey?: Key) {
+export function useSelectState(stateKey = 'select-state', initialKey: Key = 'default') {
     const store = useStore(getOrCreateStoreByKey(stateKey, initialKey));
     return {
         key: store.key,

package/src/OpenAPISpec.tsx

@@ -18,7 +18,7 @@ export function OpenAPISpec(props: {
 
     const { operation } = data;
 
-    const parameters = operation.parameters ?? [];
+    const parameters = deduplicateParameters(operation.parameters ?? []);
     const parameterGroups = groupParameters(parameters, context);
 
     const securities = 'securities' in data ? data.securities : [];
@@ -113,3 +113,23 @@ function getParameterGroupName(paramIn: string, context: OpenAPIClientContext):
             return paramIn;
     }
 }
+
+/** Deduplicate parameters by name and in.
+ * Some specs have both parameters define at path and operation level.
+ * We only want to display one of them.
+ */
+function deduplicateParameters(parameters: OpenAPI.Parameters): OpenAPI.Parameters {
+    const seen = new Set();
+
+    return parameters.filter((param) => {
+        const key = `${param.name}:${param.in}`;
+
+        if (seen.has(key)) {
+            return false;
+        }
+
+        seen.add(key);
+
+        return true;
+    });
+}

package/src/OpenAPIWebhookExample.tsx

@@ -19,9 +19,9 @@ export function OpenAPIWebhookExample(props: {
         }
 
         return Object.entries(
-            operation.requestBody.content as Record<string, OpenAPIV3.MediaTypeObject>
+            operation.requestBody.content as Record<string, OpenAPIV3.MediaTypeObject | null>
         ).map(([key, value]) => {
-            const schema = value.schema;
+            const schema = value?.schema;
 
             if (!schema) {
                 return {

package/src/StaticSection.tsx

@@ -11,7 +11,7 @@ export function SectionHeader(props: ComponentPropsWithoutRef<'div'>) {
             {...props}
             className={clsx(
                 'openapi-section-header',
-                props.className && `${props.className}-header`
+                props.className ? `${props.className}-header` : undefined
             )}
         />
     );

package/src/code-samples.test.ts

@@ -400,7 +400,7 @@ describe('python code sample generator', () => {
         const output = generator?.generate(input);
 
         expect(output).toBe(
-            'import requests\n\nresponse = requests.get(\n    "https://example.com/path",\n    headers={"Content-Type":"application/x-www-form-urlencoded"},\n    data={"key":"value"}\n)\n\ndata = response.json()'
+            'import requests\n\nresponse = requests.get(\n    "https://example.com/path",\n    headers={"Content-Type":"application/x-www-form-urlencoded"},\n    data={\n      "key": "value"\n    }\n)\n\ndata = response.json()'
         );
     });
 
@@ -415,13 +415,14 @@ describe('python code sample generator', () => {
                 key: 'value',
                 truethy: true,
                 falsey: false,
+                nullish: null,
             },
         };
 
         const output = generator?.generate(input);
 
         expect(output).toBe(
-            'import requests\n\nresponse = requests.get(\n    "https://example.com/path",\n    headers={"Content-Type":"application/json"},\n    data=json.dumps({"key":"value","truethy":True,"falsey":False})\n)\n\ndata = response.json()'
+            'import requests\n\nresponse = requests.get(\n    "https://example.com/path",\n    headers={"Content-Type":"application/json"},\n    data=json.dumps({\n      "key": "value",\n      "truethy": True,\n      "falsey": False,\n      "nullish": None\n    })\n)\n\ndata = response.json()'
         );
     });