@gitbook/react-openapi 1.2.0 → 1.3.0

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,6 +13,7 @@ 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';
@@ -19,73 +21,97 @@ import { checkIsReference, resolveDescription, resolveFirstExample } from './uti
 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 header = <OpenAPISchemaPresentation context={context} property={property} />;
+    const content = (() => {
+        if (properties?.length) {
+            return (
+                <OpenAPISchemaProperties
+                    properties={properties}
+                    circularRefs={circularRefs}
+                    context={context}
+                />
+            );
+        }
 
-                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}
+        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;
+    })();
 
-                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 (
+        <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,16 +612,47 @@ 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;
     }, []);
 }
 
+/**
+ * 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;
+    }
+
+    if (checkIsReference(schemaOrRef)) {
+        return latestAncestor?.required;
+    }
+
+    return Array.from(
+        new Set([...(latestAncestor?.required || []), ...(schemaOrRef.required || [])])
+    );
+}
+
 function getSchemaTitle(schema: OpenAPIV3.SchemaObject): string {
     // Otherwise try to infer a nice title
     let type = 'any';
@@ -587,6 +670,11 @@ function getSchemaTitle(schema: OpenAPIV3.SchemaObject): string {
         if (schema.format) {
             type += ` · ${schema.format}`;
         }
+
+        // Only add the title if it's an object (no need for the title of a string, number, etc.)
+        if (type === 'object' && schema.title) {
+            type += ` · ${schema.title.replaceAll(' ', '')}`;
+        }
     }
 
     if ('anyOf' in schema) {
@@ -601,27 +689,3 @@ function getSchemaTitle(schema: OpenAPIV3.SchemaObject): string {
 
     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();
-    }
-
-    return `${isExpanded ? tString(context.translation, 'hide') : tString(context.translation, 'show')} ${label}`;
-}

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;
 }
@@ -43,7 +43,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/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

@@ -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({"key":"value","truethy":True,"falsey":False,"nullish":None})\n)\n\ndata = response.json()'
         );
     });
 

package/src/code-samples.ts

@@ -30,7 +30,7 @@ export const codeSampleGenerators: CodeSampleGenerator[] = [
     {
         id: 'http',
         label: 'HTTP',
-        syntax: 'bash',
+        syntax: 'http',
         generate: ({ method, url, headers = {}, body }: CodeSampleInput) => {
             const { host, path } = parseHostAndPath(url);
 
@@ -362,12 +362,15 @@ const BodyGenerators = {
                         return '$$__TRUE__$$';
                     case false:
                         return '$$__FALSE__$$';
+                    case null:
+                        return '$$__NULL__$$';
                     default:
                         return value;
                 }
             })
                 .replaceAll('"$$__TRUE__$$"', 'True')
-                .replaceAll('"$$__FALSE__$$"', 'False');
+                .replaceAll('"$$__FALSE__$$"', 'False')
+                .replaceAll('"$$__NULL__$$"', 'None');
         }
 
         return { body, code, headers };

package/src/generateSchemaExample.ts

@@ -204,6 +204,14 @@ const getExampleFromSchema = (
         return cache(schema, schema.example);
     }
 
+    // Use a default value, if there’s one and it’s a string or number
+    if (
+        schema.default !== undefined &&
+        ['string', 'number', 'boolean'].includes(typeof schema.default)
+    ) {
+        return cache(schema, schema.default);
+    }
+
     // enum: [ 'available', 'pending', 'sold' ]
     if (Array.isArray(schema.enum) && schema.enum.length > 0) {
         return cache(schema, schema.enum[0]);

package/src/getDisclosureLabel.ts

@@ -0,0 +1,25 @@
+'use client';
+
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import type { OpenAPIClientContext } from './context';
+import { tString } from './translate';
+
+export 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();
+        } else {
+            label = tString(context.translation, 'properties').toLowerCase();
+        }
+    } else {
+        label = tString(context.translation, 'properties').toLowerCase();
+    }
+
+    return tString(context.translation, isExpanded ? 'hide' : 'show', label);
+}

package/src/schemas/OpenAPISchemaItem.tsx

@@ -0,0 +1,34 @@
+'use client';
+
+import { SectionBody } from '../StaticSection';
+
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import { OpenAPIDisclosure } from '../OpenAPIDisclosure';
+import { OpenAPIRootSchema } from '../OpenAPISchemaServer';
+import { Section } from '../StaticSection';
+import type { OpenAPIClientContext } from '../context';
+import { getDisclosureLabel } from '../getDisclosureLabel';
+
+export function OpenAPISchemaItem(props: {
+    name: string;
+    schema: OpenAPIV3.SchemaObject;
+    context: OpenAPIClientContext;
+}) {
+    const { schema, context, name } = props;
+
+    return (
+        <OpenAPIDisclosure
+            className="openapi-schemas-disclosure"
+            key={name}
+            icon={context.icons.plus}
+            header={name}
+            label={(isExpanded) => getDisclosureLabel({ schema, isExpanded, context })}
+        >
+            <Section className="openapi-section-schemas">
+                <SectionBody>
+                    <OpenAPIRootSchema schema={schema} context={context} />
+                </SectionBody>
+            </Section>
+        </OpenAPIDisclosure>
+    );
+}

package/src/schemas/OpenAPISchemas.tsx

@@ -1,9 +1,8 @@
 import type { OpenAPISchema } from '@gitbook/openapi-parser';
 import clsx from 'clsx';
-import { OpenAPIDisclosure } from '../OpenAPIDisclosure';
 import { OpenAPIExample } from '../OpenAPIExample';
 import { OpenAPIRootSchema } from '../OpenAPISchemaServer';
-import { Section, SectionBody, StaticSection } from '../StaticSection';
+import { StaticSection } from '../StaticSection';
 import {
     type OpenAPIContextInput,
     getOpenAPIClientContext,
@@ -11,6 +10,7 @@ import {
 } from '../context';
 import { t } from '../translate';
 import { getExampleFromSchema } from '../util/example';
+import { OpenAPISchemaItem } from './OpenAPISchemaItem';
 
 /**
  * OpenAPI Schemas component.
@@ -85,18 +85,12 @@ export function OpenAPISchemas(props: {
         <div className={clsx('openapi-schemas', className)}>
             {schemas.map(({ name, schema }) => {
                 return (
-                    <OpenAPIDisclosure
-                        className="openapi-schemas-disclosure"
+                    <OpenAPISchemaItem
                         key={name}
-                        icon={context.icons.chevronRight}
-                        label={name}
-                    >
-                        <Section className="openapi-section-schemas">
-                            <SectionBody>
-                                <OpenAPIRootSchema schema={schema} context={clientContext} />
-                            </SectionBody>
-                        </Section>
-                    </OpenAPIDisclosure>
+                        name={name}
+                        context={clientContext}
+                        schema={schema}
+                    />
                 );
             })}
         </div>

package/src/translations/de.ts

@@ -18,9 +18,11 @@ export const de = {
     nullable: 'Nullfähig',
     body: 'Rumpf',
     payload: 'Nutzlast',
-    headers: 'Kopfzeilen',
+    headers: 'Header',
+    header: 'Header',
     authorizations: 'Autorisierungen',
     responses: 'Antworten',
+    response: 'Antwort',
     path_parameters: 'Pfadparameter',
     query_parameters: 'Abfrageparameter',
     header_parameters: 'Header-Parameter',
@@ -30,8 +32,11 @@ export const de = {
     success: 'Erfolg',
     redirect: 'Umleitung',
     error: 'Fehler',
-    show: 'Anzeigen',
-    hide: 'Verstecken',
+    show: 'Zeige ${1}',
+    hide: 'Verstecke ${1}',
     available_items: 'Verfügbare Elemente',
-    child_attributes: 'Unterattribute',
+    properties: 'Eigenschaften',
+    or: 'oder',
+    and: 'und',
+    possible_values: 'Mögliche Werte',
 };

package/src/translations/en.ts

@@ -19,8 +19,10 @@ export const en = {
     body: 'Body',
     payload: 'Payload',
     headers: 'Headers',
+    header: 'Header',
     authorizations: 'Authorizations',
     responses: 'Responses',
+    response: 'Response',
     path_parameters: 'Path parameters',
     query_parameters: 'Query parameters',
     header_parameters: 'Header parameters',
@@ -30,8 +32,11 @@ export const en = {
     success: 'Success',
     redirect: 'Redirect',
     error: 'Error',
-    show: 'Show',
-    hide: 'Hide',
+    show: 'Show ${1}',
+    hide: 'Hide ${1}',
     available_items: 'Available items',
-    child_attributes: 'Child attributes',
+    possible_values: 'Possible values',
+    properties: 'Properties',
+    or: 'or',
+    and: 'and',
 };

package/src/translations/es.ts

@@ -18,9 +18,11 @@ export const es = {
     nullable: 'Nulo',
     body: 'Cuerpo',
     payload: 'Caga útil',
-    headers: 'Encabezados',
+    headers: 'Headers',
+    header: 'Header',
     authorizations: 'Autorizaciones',
     responses: 'Respuestas',
+    response: 'Respuesta',
     path_parameters: 'Parámetros de ruta',
     query_parameters: 'Parámetros de consulta',
     header_parameters: 'Parámetros de encabezado',
@@ -30,8 +32,11 @@ export const es = {
     success: 'Éxito',
     redirect: 'Redirección',
     error: 'Error',
-    show: 'Mostrar',
-    hide: 'Ocultar',
+    show: 'Mostrar ${1}',
+    hide: 'Ocultar ${1}',
     available_items: 'Elementos disponibles',
-    child_attributes: 'Atributos secundarios',
+    properties: 'Propiedades',
+    or: 'o',
+    and: 'y',
+    possible_values: 'Valores posibles',
 };