@gitbook/react-openapi 1.0.1 → 1.0.3

package/src/OpenAPIResponseExample.tsx

@@ -2,9 +2,10 @@ import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import { generateSchemaExample } from './generateSchemaExample';
 import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
 import { checkIsReference, createStateKey, resolveDescription } from './utils';
-import { stringifyOpenAPI } from './stringifyOpenAPI';
 import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
 import { InteractiveSection } from './InteractiveSection';
+import { json2xml } from './json2xml';
+import { stringifyOpenAPI } from './stringifyOpenAPI';
 
 /**
  * Display an example of the response content.
@@ -38,84 +39,51 @@ export function OpenAPIResponseExample(props: {
         return Number(a) - Number(b);
     });
 
-    const examples = responses
-        .map(([key, value]) => {
-            const responseObject = value;
-            const mediaTypeObject = (() => {
-                if (!responseObject.content) {
-                    return null;
-                }
-                const key = Object.keys(responseObject.content)[0];
-                return (
-                    responseObject.content['application/json'] ??
-                    (key ? responseObject.content[key] : null)
-                );
-            })();
-
-            if (!mediaTypeObject) {
+    const tabs = responses
+        .map(([key, responseObject]) => {
+            const description = resolveDescription(responseObject);
+
+            if (checkIsReference(responseObject)) {
                 return {
                     key: key,
                     label: key,
-                    description: resolveDescription(responseObject),
-                    body: <OpenAPIEmptyResponseExample />,
+                    description,
+                    body: (
+                        <OpenAPIExample
+                            example={getExampleFromReference(responseObject)}
+                            context={context}
+                            syntax="json"
+                        />
+                    ),
                 };
             }
 
-            const example = handleUnresolvedReference(
-                (() => {
-                    const { examples, example } = mediaTypeObject;
-                    if (examples) {
-                        const key = Object.keys(examples)[0];
-                        if (key) {
-                            // @TODO handle multiple examples
-                            const firstExample = examples[key];
-                            if (firstExample) {
-                                return firstExample;
-                            }
-                        }
-                    }
-
-                    if (example) {
-                        return { value: example };
-                    }
-
-                    const schema = mediaTypeObject.schema;
-                    if (!schema) {
-                        return null;
-                    }
-
-                    return { value: generateSchemaExample(schema) };
-                })(),
-            );
+            if (!responseObject.content || Object.keys(responseObject.content).length === 0) {
+                return {
+                    key: key,
+                    label: key,
+                    description,
+                    body: <OpenAPIEmptyResponseExample />,
+                };
+            }
 
             return {
                 key: key,
                 label: key,
                 description: resolveDescription(responseObject),
-                body: example?.value ? (
-                    <context.CodeBlock
-                        code={
-                            typeof example.value === 'string'
-                                ? example.value
-                                : stringifyOpenAPI(example.value, null, 2)
-                        }
-                        syntax="json"
-                    />
-                ) : (
-                    <OpenAPIEmptyResponseExample />
-                ),
+                body: <OpenAPIResponse context={context} content={responseObject.content} />,
             };
         })
         .filter((val): val is { key: string; label: string; body: any; description: string } =>
             Boolean(val),
         );
 
-    if (examples.length === 0) {
+    if (tabs.length === 0) {
         return null;
     }
 
     return (
-        <OpenAPITabs stateKey={createStateKey('response-example')} items={examples}>
+        <OpenAPITabs stateKey={createStateKey('response-example')} items={tabs}>
             <InteractiveSection header={<OpenAPITabsList />} className="openapi-response-example">
                 <OpenAPITabsPanels />
             </InteractiveSection>
@@ -123,6 +91,212 @@ export function OpenAPIResponseExample(props: {
     );
 }
 
+function OpenAPIResponse(props: {
+    context: OpenAPIContextProps;
+    content: {
+        [media: string]: OpenAPIV3.MediaTypeObject;
+    };
+}) {
+    const { context, content } = props;
+
+    const entries = Object.entries(content);
+    const firstEntry = entries[0];
+
+    if (!firstEntry) {
+        throw new Error('One media type is required');
+    }
+
+    if (entries.length === 1) {
+        const [mediaType, mediaTypeObject] = firstEntry;
+        return (
+            <OpenAPIResponseMediaType
+                context={context}
+                mediaType={mediaType}
+                mediaTypeObject={mediaTypeObject}
+            />
+        );
+    }
+
+    const tabs = entries.map((entry) => {
+        const [mediaType, mediaTypeObject] = entry;
+        return {
+            key: mediaType,
+            label: mediaType,
+            body: (
+                <OpenAPIResponseMediaType
+                    context={context}
+                    mediaType={mediaType}
+                    mediaTypeObject={mediaTypeObject}
+                />
+            ),
+        };
+    });
+
+    return (
+        <OpenAPITabs stateKey={createStateKey('response-media-types')} items={tabs}>
+            <InteractiveSection
+                header={<OpenAPITabsList />}
+                className="openapi-response-media-types"
+            >
+                <OpenAPITabsPanels />
+            </InteractiveSection>
+        </OpenAPITabs>
+    );
+}
+
+function OpenAPIResponseMediaType(props: {
+    mediaTypeObject: OpenAPIV3.MediaTypeObject;
+    mediaType: string;
+    context: OpenAPIContextProps;
+}) {
+    const { mediaTypeObject, mediaType } = props;
+    const examples = getExamplesFromMediaTypeObject({ mediaTypeObject, mediaType });
+    const syntax = getSyntaxFromMediaType(mediaType);
+    const firstExample = examples[0];
+
+    if (!firstExample) {
+        return <OpenAPIEmptyResponseExample />;
+    }
+
+    if (examples.length === 1) {
+        return (
+            <OpenAPIExample
+                example={firstExample.example}
+                context={props.context}
+                syntax={syntax}
+            />
+        );
+    }
+
+    const tabs = examples.map((example) => {
+        return {
+            key: example.key,
+            label: example.example.summary || example.key,
+            body: (
+                <OpenAPIExample
+                    example={firstExample.example}
+                    context={props.context}
+                    syntax={syntax}
+                />
+            ),
+        };
+    });
+
+    return (
+        <OpenAPITabs stateKey={createStateKey('response-media-type-examples')} items={tabs}>
+            <InteractiveSection
+                header={<OpenAPITabsList />}
+                className="openapi-response-media-type-examples"
+            >
+                <OpenAPITabsPanels />
+            </InteractiveSection>
+        </OpenAPITabs>
+    );
+}
+
+/**
+ * Display an example.
+ */
+function OpenAPIExample(props: {
+    example: OpenAPIV3.ExampleObject;
+    context: OpenAPIContextProps;
+    syntax: string;
+}) {
+    const { example, context, syntax } = props;
+    const code = stringifyExample({ example, xml: syntax === 'xml' });
+
+    if (code === null) {
+        return <OpenAPIEmptyResponseExample />;
+    }
+
+    return context.renderCodeBlock({ code, syntax });
+}
+
+function stringifyExample(args: { example: OpenAPIV3.ExampleObject; xml: boolean }): string | null {
+    const { example, xml } = args;
+
+    if (!example.value) {
+        return null;
+    }
+
+    if (typeof example.value === 'string') {
+        return example.value;
+    }
+
+    if (xml) {
+        return json2xml(example.value);
+    }
+
+    return stringifyOpenAPI(example.value, null, 2);
+}
+
+/**
+ * Get the syntax from a media type.
+ */
+function getSyntaxFromMediaType(mediaType: string): string {
+    if (mediaType.includes('json')) {
+        return 'json';
+    }
+
+    if (mediaType === 'application/xml') {
+        return 'xml';
+    }
+
+    return 'text';
+}
+
+/**
+ * Get examples from a media type object.
+ */
+function getExamplesFromMediaTypeObject(args: {
+    mediaType: string;
+    mediaTypeObject: OpenAPIV3.MediaTypeObject;
+}): { key: string; example: OpenAPIV3.ExampleObject }[] {
+    const { mediaTypeObject, mediaType } = args;
+    if (mediaTypeObject.examples) {
+        return Object.entries(mediaTypeObject.examples).map(([key, example]) => {
+            return {
+                key,
+                example: checkIsReference(example) ? getExampleFromReference(example) : example,
+            };
+        });
+    }
+
+    if (mediaTypeObject.example) {
+        return [{ key: 'default', example: { value: mediaTypeObject.example } }];
+    }
+
+    if (mediaTypeObject.schema) {
+        if (mediaType === 'application/xml') {
+            // @TODO normally we should use the name of the schema but we don't have it
+            // fix it when we got the reference name
+            const root = mediaTypeObject.schema.xml?.name ?? 'object';
+            return [
+                {
+                    key: 'default',
+                    example: {
+                        value: {
+                            [root]: generateSchemaExample(mediaTypeObject.schema, {
+                                xml: mediaType === 'application/xml',
+                            }),
+                        },
+                    },
+                },
+            ];
+        }
+        return [
+            {
+                key: 'default',
+                example: { value: generateSchemaExample(mediaTypeObject.schema) },
+            },
+        ];
+    }
+    return [];
+}
+
+/**
+ * Empty response example.
+ */
 function OpenAPIEmptyResponseExample() {
     return (
         <pre className="openapi-response-example-empty">
@@ -131,15 +305,9 @@ function OpenAPIEmptyResponseExample() {
     );
 }
 
-function handleUnresolvedReference(
-    input: OpenAPIV3.ExampleObject | null,
-): OpenAPIV3.ExampleObject | null {
-    const isReference = checkIsReference(input?.value);
-
-    if (isReference) {
-        // If we find a reference that wasn't resolved or needed to be resolved externally, render out the URL
-        return { value: input.value.$ref };
-    }
-
-    return input;
+/**
+ * Generate an example from a reference object.
+ */
+function getExampleFromReference(ref: OpenAPIV3.ReferenceObject): OpenAPIV3.ExampleObject {
+    return { summary: 'Unresolved reference', value: { $ref: ref.$ref } };
 }

package/src/OpenAPISchema.tsx

@@ -13,8 +13,8 @@ import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 type CircularRefsIds = Map<OpenAPIV3.SchemaObject, string>;
 
 export interface OpenAPISchemaPropertyEntry {
-    propertyName?: string;
-    required?: boolean;
+    propertyName?: string | undefined;
+    required?: boolean | undefined;
     schema: OpenAPIV3.SchemaObject;
 }
 
@@ -47,23 +47,6 @@ export function OpenAPISchemaProperty(
         ? null
         : getSchemaAlternatives(schema, new Set(circularRefs.keys()));
 
-    if ((properties && !!properties.length) || schema.type === 'object') {
-        return (
-            <InteractiveSection id={id} className={clsx('openapi-schema', className)}>
-                <OpenAPISchemaPresentation {...props} />
-                {properties && properties.length > 0 ? (
-                    <OpenAPIDisclosure context={context}>
-                        <OpenAPISchemaProperties
-                            properties={properties}
-                            circularRefs={circularRefs}
-                            context={context}
-                        />
-                    </OpenAPIDisclosure>
-                ) : null}
-            </InteractiveSection>
-        );
-    }
-
     if (alternatives?.[0]?.length) {
         return (
             <InteractiveSection id={id} className={clsx('openapi-schema', className)}>
@@ -76,6 +59,29 @@ export function OpenAPISchemaProperty(
                         context={context}
                     />
                 ))}
+                {parentCircularRef ? (
+                    <OpenAPISchemaCircularRef id={parentCircularRef} schema={schema} />
+                ) : null}
+            </InteractiveSection>
+        );
+    }
+
+    if ((properties && properties.length > 0) || schema.type === 'object') {
+        return (
+            <InteractiveSection id={id} className={clsx('openapi-schema', className)}>
+                <OpenAPISchemaPresentation {...props} />
+                {properties && properties.length > 0 ? (
+                    <OpenAPIDisclosure context={context} label={getDisclosureLabel(schema)}>
+                        <OpenAPISchemaProperties
+                            properties={properties}
+                            circularRefs={circularRefs}
+                            context={context}
+                        />
+                    </OpenAPIDisclosure>
+                ) : null}
+                {parentCircularRef ? (
+                    <OpenAPISchemaCircularRef id={parentCircularRef} schema={schema} />
+                ) : null}
             </InteractiveSection>
         );
     }
@@ -166,16 +172,24 @@ function OpenAPISchemaAlternative(props: {
     const { schema, circularRefs, context } = props;
     const id = useId();
     const subProperties = getSchemaProperties(schema);
+    const description = resolveDescription(schema);
 
     return (
-        <OpenAPIDisclosure context={context}>
-            <OpenAPISchemaProperties
-                id={id}
-                properties={subProperties ?? [{ schema }]}
-                circularRefs={subProperties ? new Map(circularRefs).set(schema, id) : circularRefs}
-                context={context}
-            />
-        </OpenAPIDisclosure>
+        <>
+            {description ? (
+                <Markdown source={description} className="openapi-schema-description" />
+            ) : null}
+            <OpenAPIDisclosure context={context} label={getDisclosureLabel(schema)}>
+                <OpenAPISchemaProperties
+                    id={id}
+                    properties={subProperties ?? [{ schema }]}
+                    circularRefs={
+                        subProperties ? new Map(circularRefs).set(schema, id) : circularRefs
+                    }
+                    context={context}
+                />
+            </OpenAPIDisclosure>
+        </>
     );
 }
 
@@ -219,7 +233,7 @@ export function OpenAPISchemaPresentation(props: OpenAPISchemaPropertyEntry) {
 
     const shouldDisplayExample = (schema: OpenAPIV3.SchemaObject): boolean => {
         return (
-            typeof schema.example === 'string' ||
+            (typeof schema.example === 'string' && !!schema.example) ||
             typeof schema.example === 'number' ||
             typeof schema.example === 'boolean' ||
             (Array.isArray(schema.example) && schema.example.length > 0) ||
@@ -234,10 +248,10 @@ export function OpenAPISchemaPresentation(props: OpenAPISchemaPropertyEntry) {
     return (
         <div className="openapi-schema-presentation">
             <OpenAPISchemaName
+                schema={schema}
                 type={getSchemaTitle(schema)}
                 propertyName={propertyName}
                 required={required}
-                deprecated={schema.deprecated}
             />
             {schema['x-deprecated-sunset'] ? (
                 <div className="openapi-deprecated-sunset openapi-schema-description openapi-markdown">
@@ -252,12 +266,7 @@ export function OpenAPISchemaPresentation(props: OpenAPISchemaPropertyEntry) {
             ) : null}
             {shouldDisplayExample(schema) ? (
                 <div className="openapi-schema-example">
-                    Example:{' '}
-                    <code>
-                        {typeof schema.example === 'string'
-                            ? schema.example
-                            : stringifyOpenAPI(schema.example)}
-                    </code>
+                    Example: <code>{formatExample(schema.example)}</code>
                 </div>
             ) : null}
             {schema.pattern ? (
@@ -276,17 +285,6 @@ export function OpenAPISchemaPresentation(props: OpenAPISchemaPropertyEntry) {
  * Get the sub-properties of a schema.
  */
 function getSchemaProperties(schema: OpenAPIV3.SchemaObject): null | OpenAPISchemaPropertyEntry[] {
-    if (schema.allOf) {
-        return schema.allOf.reduce((acc, subSchema) => {
-            const properties = getSchemaProperties(subSchema) ?? [
-                {
-                    schema: subSchema,
-                },
-            ];
-            return [...acc, ...properties];
-        }, [] as OpenAPISchemaPropertyEntry[]);
-    }
-
     // check array AND schema.items as this is sometimes null despite what the type indicates
     if (schema.type === 'array' && !!schema.items) {
         const items = schema.items;
@@ -295,6 +293,11 @@ function getSchemaProperties(schema: OpenAPIV3.SchemaObject): null | OpenAPISche
             return itemProperties;
         }
 
+        // If the items are a primitive type, we don't need to display them
+        if (['string', 'number', 'boolean', 'integer'].includes(items.type) && !items.enum) {
+            return null;
+        }
+
         return [
             {
                 propertyName: 'items',
@@ -351,8 +354,7 @@ export function getSchemaAlternatives(
     }
 
     if (schema.allOf) {
-        // allOf is managed in `getSchemaProperties`
-        return null;
+        return [flattenAlternatives('allOf', schema.allOf, downAncestors), schema.discriminator];
     }
 
     return null;
@@ -378,11 +380,6 @@ export function getSchemaTitle(
     /** If the title is inferred in a oneOf with discriminator, we can use it to optimize the title */
     discriminator?: OpenAPIV3.DiscriminatorObject,
 ): string {
-    if (schema.title) {
-        // If the schema has a title, use it
-        return schema.title;
-    }
-
     // Try using the discriminator
     if (discriminator?.propertyName && schema.properties) {
         const discriminatorProperty = schema.properties[discriminator.propertyName];
@@ -397,7 +394,7 @@ export function getSchemaTitle(
     let type = 'any';
 
     if (schema.enum) {
-        type = '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)}[]`;
@@ -407,7 +404,7 @@ export function getSchemaTitle(
         type = schema.type ?? 'object';
 
         if (schema.format) {
-            type += ` ${schema.format}`;
+            type += ` · ${schema.format}`;
         }
     } else if ('anyOf' in schema) {
         type = 'any of';
@@ -419,9 +416,35 @@ export function getSchemaTitle(
         type = 'not';
     }
 
-    if (schema.nullable) {
-        type = `nullable ${type}`;
+    return type;
+}
+
+function getDisclosureLabel(schema: OpenAPIV3.SchemaObject): string | undefined {
+    if (schema.type === 'array' && !!schema.items) {
+        if (schema.items.oneOf) {
+            return 'available items';
+        }
+
+        // Fallback to "child attributes" for enums and objects
+        if (schema.items.enum || schema.items.type === 'object') {
+            return;
+        }
+
+        return schema.items.title ?? schema.title ?? getSchemaTitle(schema.items);
     }
 
-    return type;
+    return schema.title;
+}
+
+function formatExample(example: any): string {
+    if (typeof example === 'string') {
+        return example
+            .replace(/\n/g, ' ') // Replace newlines with spaces
+            .replace(/\s+/g, ' ') // Collapse multiple spaces/newlines into a single space
+            .replace(/([\{\}:,])\s+/g, '$1 ') // Ensure a space after {, }, :, and ,
+            .replace(/\s+([\{\}:,])/g, ' $1') // Ensure a space before {, }, :, and ,
+            .trim();
+    }
+
+    return stringifyOpenAPI(example);
 }

package/src/OpenAPISchemaName.tsx

@@ -1,8 +1,10 @@
+import { OpenAPIV3 } from '@gitbook/openapi-parser';
+
 interface OpenAPISchemaNameProps {
+    schema?: OpenAPIV3.SchemaObject;
     propertyName?: string | JSX.Element;
     required?: boolean;
     type?: string;
-    deprecated?: boolean;
 }
 
 /**
@@ -10,18 +12,48 @@ interface OpenAPISchemaNameProps {
  * It includes the property name, type, required and deprecated status.
  */
 export function OpenAPISchemaName(props: OpenAPISchemaNameProps): JSX.Element {
-    const { type, propertyName, required, deprecated } = props;
+    const { schema, type, propertyName, required } = props;
+
+    const additionalItems = schema && getAdditionalItems(schema);
 
     return (
         <div className="openapi-schema-name">
             {propertyName ? (
-                <span data-deprecated={deprecated} className="openapi-schema-propertyname">
+                <span data-deprecated={schema?.deprecated} className="openapi-schema-propertyname">
                     {propertyName}
                 </span>
             ) : null}
-            {type ? <span className="openapi-schema-type">{type}</span> : null}
+            <span>
+                {type ? <span className="openapi-schema-type">{type}</span> : null}
+                {additionalItems ? (
+                    <span className="openapi-schema-type">{additionalItems}</span>
+                ) : null}
+            </span>
             {required ? <span className="openapi-schema-required">required</span> : null}
-            {deprecated ? <span className="openapi-deprecated">Deprecated</span> : null}
+            {schema?.deprecated ? <span className="openapi-deprecated">Deprecated</span> : null}
         </div>
     );
 }
+
+function getAdditionalItems(schema: OpenAPIV3.SchemaObject): string {
+    let additionalItems = '';
+
+    if (schema.minimum || schema.minLength) {
+        additionalItems += ` · min: ${schema.minimum || schema.minLength}`;
+    }
+
+    if (schema.maximum || schema.maxLength) {
+        additionalItems += ` · max: ${schema.maximum || schema.maxLength}`;
+    }
+
+    // If the schema has a default value, we display it
+    if (typeof schema.default !== 'undefined') {
+        additionalItems += ` · default: ${schema.default}`;
+    }
+
+    if (schema.nullable) {
+        additionalItems = ` | nullable`;
+    }
+
+    return additionalItems;
+}

package/src/OpenAPISpec.tsx

@@ -8,7 +8,7 @@ import { OpenAPIResponses } from './OpenAPIResponses';
 import { OpenAPISchemaProperties } from './OpenAPISchema';
 import { OpenAPISecurities } from './OpenAPISecurities';
 import type { OpenAPIClientContext, OpenAPIOperationData } from './types';
-import { resolveDescription } from './utils';
+import { parameterToProperty } from './utils';
 
 /**
  * Client component to render the spec for the request and response.
@@ -38,22 +38,7 @@ export function OpenAPISpec(props: { data: OpenAPIOperationData; context: OpenAP
                         header={group.label}
                     >
                         <OpenAPISchemaProperties
-                            properties={group.parameters.map((parameter) => {
-                                const description = resolveDescription(parameter);
-                                return {
-                                    propertyName: parameter.name,
-                                    schema: {
-                                        // Description of the parameter is defined at the parameter level
-                                        // we use display it if the schema doesn't override it
-                                        description: description,
-                                        example: parameter.example,
-                                        // Deprecated can be defined at the parameter level
-                                        deprecated: parameter.deprecated,
-                                        ...(parameter.schema ?? {}),
-                                    },
-                                    required: parameter.required,
-                                };
-                            })}
+                            properties={group.parameters.map(parameterToProperty)}
                             context={context}
                         />
                     </InteractiveSection>