@gitbook/react-openapi 0.7.0 → 1.0.0

package/src/OpenAPIResponses.tsx

@@ -1,16 +1,16 @@
-import * as React from 'react';
-import classNames from 'classnames';
-import { OpenAPIV3 } from 'openapi-types';
-import { createStateKey, noReference } from './utils';
+import type { OpenAPIV3, OpenAPIV3_1 } from '@gitbook/openapi-parser';
+import { createStateKey, resolveDescription } from './utils';
 import { OpenAPIResponse } from './OpenAPIResponse';
 import { OpenAPIClientContext } from './types';
 import { InteractiveSection } from './InteractiveSection';
+import { OpenAPIDisclosureGroup } from './OpenAPIDisclosureGroup';
+import { Markdown } from './Markdown';
 
 /**
  * Display an interactive response body.
  */
 export function OpenAPIResponses(props: {
-    responses: OpenAPIV3.ResponsesObject;
+    responses: OpenAPIV3.ResponsesObject | OpenAPIV3_1.ResponsesObject;
     context: OpenAPIClientContext;
 }) {
     const { responses, context } = props;
@@ -18,15 +18,51 @@ export function OpenAPIResponses(props: {
     return (
         <InteractiveSection
             stateKey={createStateKey('response', context.blockKey)}
-            header="Response"
-            className={classNames('openapi-responses')}
-            tabs={Object.entries(responses).map(([statusCode, response]) => {
-                return {
-                    key: statusCode,
-                    label: statusCode,
-                    body: <OpenAPIResponse response={noReference(response)} context={context} />,
-                };
-            })}
-        />
+            header="Responses"
+            className="openapi-responses"
+        >
+            <OpenAPIDisclosureGroup
+                allowsMultipleExpanded
+                icon={context.icons.chevronRight}
+                groups={Object.entries(responses).map(
+                    ([statusCode, response]: [string, OpenAPIV3.ResponseObject]) => {
+                        const content = Object.entries(response.content ?? {});
+                        const description = resolveDescription(response);
+
+                        return {
+                            id: statusCode,
+                            label: (
+                                <div
+                                    className="openapi-response-tab-content"
+                                    key={`response-${statusCode}`}
+                                >
+                                    <span className="openapi-response-statuscode">
+                                        {statusCode}
+                                    </span>
+                                    {description ? (
+                                        <Markdown
+                                            source={description}
+                                            className="openapi-response-description"
+                                        />
+                                    ) : null}
+                                </div>
+                            ),
+                            tabs: content.map(([contentType, mediaType]) => ({
+                                id: contentType,
+                                label: contentType,
+                                body: (
+                                    <OpenAPIResponse
+                                        key={`$response-${statusCode}-${contentType}`}
+                                        response={response}
+                                        mediaType={mediaType}
+                                        context={context}
+                                    />
+                                ),
+                            })),
+                        };
+                    },
+                )}
+            />
+        </InteractiveSection>
     );
 }

package/src/OpenAPISchema.test.ts

@@ -1,6 +1,6 @@
 import { it, describe, expect } from 'bun:test';
 import { getSchemaAlternatives } from './OpenAPISchema';
-import { OpenAPIV3 } from 'openapi-types';
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 
 describe('getSchemaAlternatives', () => {
     it('should flatten oneOf', () => {

package/src/OpenAPISchema.tsx

@@ -1,16 +1,18 @@
-import classNames from 'classnames';
-import { OpenAPIV3 } from 'openapi-types';
-import React, { useId } from 'react';
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import clsx from 'clsx';
+import { useId } from 'react';
 
 import { InteractiveSection } from './InteractiveSection';
 import { Markdown } from './Markdown';
-import { SYMBOL_REF_RESOLVED } from './resolveOpenAPIPath';
-import { OpenAPIClientContext } from './types';
-import { noReference } from './utils';
+import type { OpenAPIClientContext } from './types';
+import { checkIsReference, noReference, resolveDescription } from './utils';
+import { stringifyOpenAPI } from './stringifyOpenAPI';
+import { OpenAPISchemaName } from './OpenAPISchemaName';
+import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 
 type CircularRefsIds = Map<OpenAPIV3.SchemaObject, string>;
 
-interface OpenAPISchemaPropertyEntry {
+export interface OpenAPISchemaPropertyEntry {
     propertyName?: string;
     required?: boolean;
     schema: OpenAPIV3.SchemaObject;
@@ -28,8 +30,6 @@ export function OpenAPISchemaProperty(
     },
 ) {
     const {
-        propertyName,
-        required,
         schema,
         circularRefs: parentCircularRefs = new Map<OpenAPIV3.SchemaObject, string>(),
         context,
@@ -47,71 +47,42 @@ export function OpenAPISchemaProperty(
         ? null
         : getSchemaAlternatives(schema, new Set(circularRefs.keys()));
 
-    const shouldDisplayExample = (schema: OpenAPIV3.SchemaObject): boolean => {
+    if ((properties && !!properties.length) || schema.type === 'object') {
         return (
-            typeof schema.example === 'string' ||
-            typeof schema.example === 'number' ||
-            typeof schema.example === 'boolean'
+            <InteractiveSection id={id} className={clsx('openapi-schema', className)}>
+                <OpenAPISchemaPresentation {...props} />
+                <OpenAPIDisclosure context={context}>
+                    {properties && properties.length > 0 ? (
+                        <OpenAPISchemaProperties
+                            properties={properties}
+                            circularRefs={circularRefs}
+                            context={context}
+                        />
+                    ) : null}
+                </OpenAPIDisclosure>
+            </InteractiveSection>
         );
-    };
-    return (
-        <InteractiveSection
-            id={id}
-            className={classNames('openapi-schema', className)}
-            toggeable={!!properties || !!alternatives}
-            defaultOpened={!!context.defaultInteractiveOpened}
-            toggleOpenIcon={context.icons.chevronRight}
-            toggleCloseIcon={context.icons.chevronDown}
-            tabs={alternatives?.[0].map((alternative, index) => ({
-                key: `${index}`,
-                label: getSchemaTitle(alternative, alternatives[1]),
-                body: circularRefs.has(alternative) ? (
-                    <OpenAPISchemaCircularRef
-                        id={circularRefs.get(alternative)!}
-                        schema={alternative}
-                    />
-                ) : (
+    }
+
+    if (alternatives?.[0]?.length) {
+        return (
+            <InteractiveSection id={id} className={clsx('openapi-schema', className)}>
+                <OpenAPISchemaPresentation {...props} />
+                {alternatives[0].map((alternative, index) => (
                     <OpenAPISchemaAlternative
+                        key={index}
                         schema={alternative}
                         circularRefs={circularRefs}
                         context={context}
                     />
-                ),
-            }))}
-            header={
-                <div className={classNames('openapi-schema-presentation')}>
-                    <div className={classNames('openapi-schema-name')}>
-                        {propertyName ? (
-                            <span className={classNames('openapi-schema-propertyname')}>
-                                {propertyName}
-                            </span>
-                        ) : null}
-                        {required ? (
-                            <span className={classNames('openapi-schema-required')}>*</span>
-                        ) : null}
-                        <span className={classNames('openapi-schema-type')}>
-                            {getSchemaTitle(schema)}
-                        </span>
-                    </div>
-                    {schema.description ? (
-                        <Markdown
-                            source={schema.description}
-                            className="openapi-schema-description"
-                        />
-                    ) : null}
-                    {shouldDisplayExample(schema) ? (
-                        <span className="openapi-schema-example">
-                            Example: <code>{JSON.stringify(schema.example)}</code>
-                        </span>
-                    ) : null}
-                    {schema.pattern ? (
-                        <div className="openapi-schema-pattern">
-                            Pattern: <code>{schema.pattern}</code>
-                        </div>
-                    ) : null}
-                </div>
-            }
-        >
+                ))}
+            </InteractiveSection>
+        );
+    }
+
+    return (
+        <InteractiveSection id={id} className={clsx('openapi-schema', className)}>
+            <OpenAPISchemaPresentation {...props} />
             {(properties && properties.length > 0) ||
             (schema.enum && schema.enum.length > 0) ||
             parentCircularRef ? (
@@ -123,9 +94,6 @@ export function OpenAPISchemaProperty(
                             context={context}
                         />
                     ) : null}
-                    {schema.enum && schema.enum.length > 0 ? (
-                        <OpenAPISchemaEnum enumValues={schema.enum} />
-                    ) : null}
                     {parentCircularRef ? (
                         <OpenAPISchemaCircularRef id={parentCircularRef} schema={schema} />
                     ) : null}
@@ -151,7 +119,7 @@ export function OpenAPISchemaProperties(props: {
     }
 
     return (
-        <div id={id} className={classNames('openapi-schema-properties')}>
+        <div id={id} className="openapi-schema-properties">
             {properties.map((property) => (
                 <OpenAPISchemaProperty
                     key={property.propertyName}
@@ -200,12 +168,14 @@ function OpenAPISchemaAlternative(props: {
     const subProperties = getSchemaProperties(schema);
 
     return (
-        <OpenAPISchemaProperties
-            id={id}
-            properties={subProperties ?? [{ schema }]}
-            circularRefs={subProperties ? new Map(circularRefs).set(schema, id) : circularRefs}
-            context={context}
-        />
+        <OpenAPIDisclosure context={context}>
+            <OpenAPISchemaProperties
+                id={id}
+                properties={subProperties ?? [{ schema }]}
+                circularRefs={subProperties ? new Map(circularRefs).set(schema, id) : circularRefs}
+                context={context}
+            />
+        </OpenAPIDisclosure>
     );
 }
 
@@ -231,9 +201,73 @@ export function OpenAPISchemaEnum(props: { enumValues: any[] }) {
 
     return (
         <div className="openapi-schema-enum">
-            {enumValues.map((value, index) => (
-                <span key={index} className="openapi-schema-enum-value">{`${value}`}</span>
-            ))}
+            <span>
+                Options:{' '}
+                {enumValues.map((value, index) => (
+                    <span key={index} className="openapi-schema-enum-value">
+                        <code>{`${value}`}</code>
+                        {index < enumValues.length - 1 ? ', ' : ''}
+                    </span>
+                ))}
+            </span>
+        </div>
+    );
+}
+
+export function OpenAPISchemaPresentation(props: OpenAPISchemaPropertyEntry) {
+    const { schema, propertyName, required } = props;
+
+    const shouldDisplayExample = (schema: OpenAPIV3.SchemaObject): boolean => {
+        return (
+            typeof schema.example === 'string' ||
+            typeof schema.example === 'number' ||
+            typeof schema.example === 'boolean' ||
+            (Array.isArray(schema.example) && schema.example.length > 0) ||
+            (typeof schema.example === 'object' &&
+                schema.example !== null &&
+                Object.keys(schema.example).length > 0)
+        );
+    };
+
+    const description = resolveDescription(schema);
+
+    return (
+        <div className="openapi-schema-presentation">
+            <OpenAPISchemaName
+                type={getSchemaTitle(schema)}
+                propertyName={propertyName}
+                required={required}
+                deprecated={schema.deprecated}
+            />
+            {schema['x-deprecated-sunset'] ? (
+                <div className="openapi-deprecated-sunset openapi-schema-description openapi-markdown">
+                    Sunset date:{' '}
+                    <span className="openapi-deprecated-sunset-date">
+                        {schema['x-deprecated-sunset']}
+                    </span>
+                </div>
+            ) : null}
+            {description ? (
+                <Markdown source={description} className="openapi-schema-description" />
+            ) : null}
+            {shouldDisplayExample(schema) ? (
+                <div className="openapi-schema-example">
+                    Example:{' '}
+                    <code>
+                        {typeof schema.example === 'string'
+                            ? schema.example
+                            : stringifyOpenAPI(schema.example)}
+                    </code>
+                </div>
+            ) : null}
+            {schema.pattern ? (
+                <div className="openapi-schema-pattern">
+                    Pattern: <code>{schema.pattern}</code>
+                </div>
+            ) : null}
+            {schema.enum && schema.enum.length > 0 ? (
+                <OpenAPISchemaEnum enumValues={schema.enum} />
+            ) : null}
         </div>
     );
 }
@@ -274,10 +308,10 @@ function getSchemaProperties(schema: OpenAPIV3.SchemaObject): null | OpenAPISche
 
         if (schema.properties) {
             Object.entries(schema.properties).forEach(([propertyName, rawPropertySchema]) => {
-                const propertySchema = noReference(rawPropertySchema);
-                if (propertySchema.deprecated) {
-                    return;
-                }
+                const isReference = checkIsReference(rawPropertySchema);
+                const propertySchema: OpenAPIV3.SchemaObject = isReference
+                    ? { propertyName }
+                    : rawPropertySchema;
 
                 result.push({
                     propertyName,
@@ -349,7 +383,7 @@ function flattenAlternatives(
     }, [] as OpenAPIV3.SchemaObject[]);
 }
 
-function getSchemaTitle(
+export function getSchemaTitle(
     schema: OpenAPIV3.SchemaObject,
 
     /** If the title is inferred in a oneOf with discriminator, we can use it to optimize the title */
@@ -361,7 +395,7 @@ function getSchemaTitle(
     }
 
     // Try using the discriminator
-    if (discriminator && schema.properties) {
+    if (discriminator?.propertyName && schema.properties) {
         const discriminatorProperty = noReference(schema.properties[discriminator.propertyName]);
         if (discriminatorProperty) {
             if (discriminatorProperty.enum) {
@@ -377,12 +411,14 @@ function getSchemaTitle(
         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 = `array of ${getSchemaTitle(noReference(schema.items))}`;
+        type = `${getSchemaTitle(noReference(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})`;
+            type += ` ${schema.format}`;
         }
     } else if ('anyOf' in schema) {
         type = 'any of';
@@ -394,10 +430,6 @@ function getSchemaTitle(
         type = 'not';
     }
 
-    if (SYMBOL_REF_RESOLVED in schema) {
-        type = `${schema[SYMBOL_REF_RESOLVED]} (${type})`;
-    }
-
     if (schema.nullable) {
         type = `nullable ${type}`;
     }

package/src/OpenAPISchemaName.tsx

@@ -0,0 +1,27 @@
+interface OpenAPISchemaNameProps {
+    propertyName?: string | JSX.Element;
+    required?: boolean;
+    type?: string;
+    deprecated?: boolean;
+}
+
+/**
+ * Display the schema name row.
+ * It includes the property name, type, required and deprecated status.
+ */
+export function OpenAPISchemaName(props: OpenAPISchemaNameProps): JSX.Element {
+    const { type, propertyName, required, deprecated } = props;
+
+    return (
+        <div className="openapi-schema-name">
+            {propertyName ? (
+                <span data-deprecated={deprecated} className="openapi-schema-propertyname">
+                    {propertyName}
+                </span>
+            ) : null}
+            {type ? <span className="openapi-schema-type">{type}</span> : null}
+            {required ? <span className="openapi-schema-required">required</span> : null}
+            {deprecated ? <span className="openapi-deprecated">Deprecated</span> : null}
+        </div>
+    );
+}

package/src/OpenAPISecurities.tsx

@@ -1,9 +1,9 @@
-import * as React from 'react';
-import { OpenAPIV3 } from 'openapi-types';
-import { OpenAPIClientContext } from './types';
+import type { OpenAPIV3_1 } from '@gitbook/openapi-parser';
+import type { OpenAPIClientContext, OpenAPIOperationData } from './types';
 import { InteractiveSection } from './InteractiveSection';
 import { Markdown } from './Markdown';
-import { OpenAPIOperationData } from './fetchOpenAPIOperation';
+import { OpenAPISchemaName } from './OpenAPISchemaName';
+import { resolveDescription } from './utils';
 
 /**
  * Present securities authorization that can be used for this operation.
@@ -20,26 +20,29 @@ export function OpenAPISecurities(props: {
 
     return (
         <InteractiveSection
-            header="Authorization"
-            className="openapi-securities"
+            header="Authorizations"
             toggeable
             defaultOpened={false}
-            toggleCloseIcon={context.icons.chevronDown}
-            toggleOpenIcon={context.icons.chevronRight}
+            toggleIcon={context.icons.chevronRight}
+            className="openapi-securities"
             tabs={securities.map(([key, security]) => {
+                const description = resolveDescription(security);
                 return {
                     key: key,
                     label: key,
                     body: (
-                        <>
-                            <p className="openapi-securities-label">{getLabelForType(security)}</p>
-                            {security.description ? (
-                                <Markdown
-                                    source={security.description}
-                                    className="openapi-securities-description"
-                                />
-                            ) : null}
-                        </>
+                        <div className="openapi-schema-body">
+                            <div className="openapi-schema-presentation">
+                                {getLabelForType(security)}
+
+                                {description ? (
+                                    <Markdown
+                                        source={description}
+                                        className="openapi-securities-description"
+                                    />
+                                ) : null}
+                            </div>
+                        </div>
                     ),
                 };
             })}
@@ -47,24 +50,42 @@ export function OpenAPISecurities(props: {
     );
 }
 
-function getLabelForType(security: OpenAPIV3.SecuritySchemeObject) {
+function getLabelForType(security: OpenAPIV3_1.SecuritySchemeObject) {
     switch (security.type) {
         case 'apiKey':
-            return 'API Key';
+            return (
+                <OpenAPISchemaName
+                    propertyName={security.name ?? 'apiKey'}
+                    type="string"
+                    required
+                />
+            );
         case 'http':
             if (security.scheme === 'basic') {
-                return 'Basic Auth';
+                return <OpenAPISchemaName propertyName="Authorization" type="string" required />;
             }
 
             if (security.scheme == 'bearer') {
-                return `Bearer Token ${security.bearerFormat ? `(${security.bearerFormat})` : ''}`;
+                const description = resolveDescription(security);
+                return (
+                    <>
+                        <OpenAPISchemaName propertyName="Authorization" type="string" required />
+                        {/** Show a default description if none is provided */}
+                        {!description ? (
+                            <Markdown
+                                source={`Bearer authentication header of the form Bearer ${`&lt;token&gt;`}.`}
+                                className="openapi-securities-description"
+                            />
+                        ) : null}
+                    </>
+                );
             }
 
-            return 'HTTP';
+            return <OpenAPISchemaName propertyName="HTTP" required />;
         case 'oauth2':
-            return 'OAuth2';
+            return <OpenAPISchemaName propertyName="OAuth2" required />;
         case 'openIdConnect':
-            return 'OpenID Connect';
+            return <OpenAPISchemaName propertyName="OpenID Connect" required />;
         default:
             // @ts-ignore
             return security.type;

package/src/OpenAPIServerURL.tsx

@@ -1,5 +1,4 @@
-import * as React from 'react';
-import { OpenAPIV3 } from 'openapi-types';
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import { OpenAPIServerURLVariable } from './OpenAPIServerURLVariable';
 
 /**
@@ -9,6 +8,10 @@ export function OpenAPIServerURL(props: { servers: OpenAPIV3.ServerObject[] }) {
     const { servers } = props;
     const server = servers[0];
 
+    if (!server) {
+        return null;
+    }
+
     const parts = parseServerURL(server?.url ?? '');
 
     return (
@@ -17,16 +20,13 @@ export function OpenAPIServerURL(props: { servers: OpenAPIV3.ServerObject[] }) {
                 if (part.kind === 'text') {
                     return <span key={i}>{part.text}</span>;
                 } else {
-                    if (!server.variables?.[part.name]) {
+                    const variable = server.variables?.[part.name];
+                    if (!variable) {
                         return <span key={i}>{`{${part.name}}`}</span>;
                     }
 
                     return (
-                        <OpenAPIServerURLVariable
-                            key={i}
-                            name={part.name}
-                            variable={server.variables[part.name]}
-                        />
+                        <OpenAPIServerURLVariable key={i} name={part.name} variable={variable} />
                     );
                 }
             })}
@@ -39,6 +39,9 @@ export function OpenAPIServerURL(props: { servers: OpenAPIV3.ServerObject[] }) {
  */
 export function getServersURL(servers: OpenAPIV3.ServerObject[]): string {
     const server = servers[0];
+    if (!server) {
+        return '';
+    }
     const parts = parseServerURL(server?.url ?? '');
 
     return parts
@@ -56,10 +59,14 @@ function parseServerURL(url: string) {
     const parts = url.split(/{([^}]+)}/g);
     const result: Array<{ kind: 'variable'; name: string } | { kind: 'text'; text: string }> = [];
     for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        if (!part) {
+            continue;
+        }
         if (i % 2 === 0) {
-            result.push({ kind: 'text', text: parts[i] });
+            result.push({ kind: 'text', text: part });
         } else {
-            result.push({ kind: 'variable', name: parts[i] });
+            result.push({ kind: 'variable', name: part });
         }
     }
     return result;

package/src/OpenAPIServerURLVariable.tsx

@@ -1,8 +1,6 @@
 'use client';
 
-import * as React from 'react';
-import classNames from 'classnames';
-import { OpenAPIV3 } from 'openapi-types';
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 
 /**
  * Interactive component to show the value of a server variable and let the user change it.
@@ -12,5 +10,5 @@ export function OpenAPIServerURLVariable(props: {
     variable: OpenAPIV3.ServerVariableObject;
 }) {
     const { variable } = props;
-    return <span className={classNames('openapi-url-var')}>{variable.default}</span>;
+    return <span className="openapi-url-var">{variable.default}</span>;
 }