@gitbook/react-openapi 1.1.10 → 1.2.0

package/src/OpenAPIOperationDescription.tsx

@@ -0,0 +1,34 @@
+import type { OpenAPICustomOperationProperties, OpenAPIV3 } from '@gitbook/openapi-parser';
+import { Markdown } from './Markdown';
+import type { OpenAPIContext } from './context';
+import { resolveDescription } from './utils';
+
+/**
+ * Display the description of an OpenAPI operation.
+ */
+export function OpenAPIOperationDescription(props: {
+    operation: OpenAPIV3.OperationObject<OpenAPICustomOperationProperties>;
+    context: OpenAPIContext;
+}) {
+    const { operation } = props;
+    if (operation['x-gitbook-description-document']) {
+        return (
+            <div className="openapi-intro">
+                {props.context.renderDocument({
+                    document: operation['x-gitbook-description-document'],
+                })}
+            </div>
+        );
+    }
+
+    const description = resolveDescription(operation);
+    if (!description) {
+        return null;
+    }
+
+    return (
+        <div className="openapi-intro">
+            <Markdown className="openapi-description" source={description} />
+        </div>
+    );
+}

package/src/OpenAPIOperationStability.tsx

@@ -0,0 +1,39 @@
+import type { OpenAPIStability } from '@gitbook/openapi-parser';
+import type { OpenAPIContext } from './context';
+import { t } from './translate';
+
+/**
+ * Display the stability of an OpenAPI operation.
+ */
+export function OpenAPIOperationStability(props: {
+    stability: OpenAPIStability;
+    context: OpenAPIContext;
+}) {
+    const { stability, context } = props;
+
+    const stabilityLabel = getStabilityLabel(stability, context);
+
+    if (!stabilityLabel) {
+        return null;
+    }
+
+    return (
+        <div className={`openapi-stability openapi-stability-${stability}`}>{stabilityLabel}</div>
+    );
+}
+
+/**
+ * Get the stability label for the given stability level.
+ */
+function getStabilityLabel(stability: OpenAPIStability, context: OpenAPIContext) {
+    switch (stability) {
+        case 'experimental':
+            return t(context.translation, 'stability_experimental');
+        case 'alpha':
+            return t(context.translation, 'stability_alpha');
+        case 'beta':
+            return t(context.translation, 'stability_beta');
+        default:
+            return null;
+    }
+}

package/src/OpenAPIPath.tsx

@@ -1,4 +1,5 @@
 import { OpenAPICopyButton } from './OpenAPICopyButton';
+import { type OpenAPIUniversalContext, getOpenAPIClientContext } from './context';
 import type { OpenAPIOperationData } from './types';
 import { getDefaultServerURL } from './util/server';
 
@@ -7,6 +8,7 @@ import { getDefaultServerURL } from './util/server';
  */
 export function OpenAPIPath(props: {
     data: OpenAPIOperationData;
+    context: OpenAPIUniversalContext;
     /** Whether to show the server URL.
      * @default true
      */
@@ -17,7 +19,7 @@ export function OpenAPIPath(props: {
      */
     canCopy?: boolean;
 }) {
-    const { data, withServer = true, canCopy = true } = props;
+    const { data, context, withServer = true, canCopy = true } = props;
     const { method, path, operation } = data;
 
     const server = getDefaultServerURL(data.servers);
@@ -41,6 +43,7 @@ export function OpenAPIPath(props: {
                 className="openapi-path-title"
                 data-deprecated={operation.deprecated}
                 isDisabled={!canCopy}
+                context={getOpenAPIClientContext(context)}
             >
                 {element}
             </OpenAPICopyButton>

package/src/OpenAPIRequestBody.tsx

@@ -1,8 +1,10 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import { InteractiveSection } from './InteractiveSection';
 import { OpenAPIRootSchema } from './OpenAPISchemaServer';
-import type { OpenAPIClientContext } from './types';
-import { checkIsReference } from './utils';
+import type { OpenAPIClientContext } from './context';
+import { t } from './translate';
+import type { OpenAPIOperationData, OpenAPIWebhookData } from './types';
+import { checkIsReference, createStateKey } from './utils';
 
 /**
  * Display an interactive request body.
@@ -10,8 +12,9 @@ import { checkIsReference } from './utils';
 export function OpenAPIRequestBody(props: {
     requestBody: OpenAPIV3.RequestBodyObject | OpenAPIV3.ReferenceObject;
     context: OpenAPIClientContext;
+    data: OpenAPIOperationData | OpenAPIWebhookData;
 }) {
-    const { requestBody, context } = props;
+    const { requestBody, context, data } = props;
 
     if (checkIsReference(requestBody)) {
         return null;
@@ -19,8 +22,10 @@ export function OpenAPIRequestBody(props: {
 
     return (
         <InteractiveSection
-            header="Body"
+            header={t(context.translation, 'name' in data ? 'payload' : 'body')}
             className="openapi-requestbody"
+            stateKey={createStateKey('request-body-media-type', context.blockKey)}
+            selectIcon={context.icons.chevronDown}
             tabs={Object.entries(requestBody.content ?? {}).map(
                 ([contentType, mediaTypeObject]) => {
                     return {

package/src/OpenAPIResponse.tsx

@@ -1,7 +1,7 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 import { OpenAPISchemaProperties } from './OpenAPISchemaServer';
-import type { OpenAPIClientContext } from './types';
+import type { OpenAPIClientContext } from './context';
 import { parameterToProperty, resolveDescription } from './utils';
 
 /**
@@ -27,7 +27,7 @@ export function OpenAPIResponse(props: {
     return (
         <div className="openapi-response-body">
             {headers.length > 0 ? (
-                <OpenAPIDisclosure context={context} label="Headers">
+                <OpenAPIDisclosure icon={context.icons.plus} label="Headers">
                     <OpenAPISchemaProperties
                         properties={headers.map(([name, header]) =>
                             parameterToProperty({ name, ...header })

package/src/OpenAPIResponseExample.tsx

@@ -1,21 +1,19 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import { Markdown } from './Markdown';
-import {
-    OpenAPIEmptyExample,
-    OpenAPIExample,
-    getExampleFromReference,
-    getExamplesFromMediaTypeObject,
-} from './OpenAPIExample';
-import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
-import { StaticSection } from './StaticSection';
-import type { OpenAPIContext, OpenAPIOperationData } from './types';
-import { checkIsReference, createStateKey, resolveDescription } from './utils';
+import { OpenAPIEmptyExample, OpenAPIExample } from './OpenAPIExample';
+import { OpenAPIMediaTypeContent } from './OpenAPIMediaType';
+import { OpenAPIResponseExampleContent } from './OpenAPIResponseExampleContent';
+import { type OpenAPIContext, getOpenAPIClientContext } from './context';
+import type { OpenAPIOperationData, OpenAPIWebhookData } from './types';
+import { getExampleFromReference, getExamples } from './util/example';
+import { createStateKey, getStatusCodeDefaultLabel } from './utils';
+import { checkIsReference, resolveDescription } from './utils';
 
 /**
  * Display an example of the response content.
  */
 export function OpenAPIResponseExample(props: {
-    data: OpenAPIOperationData;
+    data: OpenAPIOperationData | OpenAPIWebhookData;
     context: OpenAPIContext;
 }) {
     const { data, context } = props;
@@ -45,36 +43,41 @@ export function OpenAPIResponseExample(props: {
 
     const tabs = responses.map(([key, responseObject]) => {
         const description = resolveDescription(responseObject);
+        const label = description ? (
+            <Markdown source={description} />
+        ) : (
+            getStatusCodeDefaultLabel(key, context)
+        );
 
         if (checkIsReference(responseObject)) {
             return {
                 key: key,
-                label: key,
+                label,
+                statusCode: key,
                 body: (
                     <OpenAPIExample
-                        example={getExampleFromReference(responseObject)}
+                        example={getExampleFromReference(responseObject, context)}
                         context={context}
                         syntax="json"
                     />
                 ),
-                footer: description ? <Markdown source={description} /> : undefined,
             };
         }
 
         if (!responseObject.content || Object.keys(responseObject.content).length === 0) {
             return {
                 key: key,
-                label: key,
-                body: <OpenAPIEmptyExample />,
-                footer: description ? <Markdown source={description} /> : undefined,
+                label,
+                statusCode: key,
+                body: <OpenAPIEmptyExample context={context} />,
             };
         }
 
         return {
             key: key,
-            label: key,
+            label,
+            statusCode: key,
             body: <OpenAPIResponse context={context} content={responseObject.content} />,
-            footer: description ? <Markdown source={description} /> : undefined,
         };
     });
 
@@ -83,11 +86,11 @@ export function OpenAPIResponseExample(props: {
     }
 
     return (
-        <OpenAPITabs stateKey={createStateKey('response-example')} items={tabs}>
-            <StaticSection header={<OpenAPITabsList />} className="openapi-panel">
-                <OpenAPITabsPanels />
-            </StaticSection>
-        </OpenAPITabs>
+        <OpenAPIResponseExampleContent
+            selectIcon={context.icons.chevronDown}
+            blockKey={context.blockKey}
+            items={tabs}
+        />
     );
 }
 
@@ -106,98 +109,26 @@ function OpenAPIResponse(props: {
         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}>
-            <StaticSection header={<OpenAPITabsList />} className="openapi-response-media-types">
-                <OpenAPITabsPanels />
-            </StaticSection>
-        </OpenAPITabs>
-    );
-}
-
-function OpenAPIResponseMediaType(props: {
-    mediaTypeObject: OpenAPIV3.MediaTypeObject;
-    mediaType: string;
-    context: OpenAPIContext;
-}) {
-    const { mediaTypeObject, mediaType } = props;
-    const examples = getExamplesFromMediaTypeObject({ mediaTypeObject, mediaType });
-    const syntax = getSyntaxFromMediaType(mediaType);
-    const firstExample = examples[0];
-
-    if (!firstExample) {
-        return <OpenAPIEmptyExample />;
-    }
-
-    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={example.example} context={props.context} syntax={syntax} />
-            ),
+            body: <></>,
+            examples: getExamples({
+                mediaTypeObject,
+                mediaType,
+                context,
+            }),
         };
     });
 
     return (
-        <OpenAPITabs stateKey={createStateKey('response-media-type-examples')} items={tabs}>
-            <StaticSection
-                header={<OpenAPITabsList />}
-                className="openapi-response-media-type-examples"
-            >
-                <OpenAPITabsPanels />
-            </StaticSection>
-        </OpenAPITabs>
+        <OpenAPIMediaTypeContent
+            selectIcon={context.icons.chevronDown}
+            stateKey={createStateKey('response-media-types', context.blockKey)}
+            items={tabs}
+            context={getOpenAPIClientContext(context)}
+        />
     );
 }
-
-/**
- * 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';
-}

package/src/OpenAPIResponseExampleContent.tsx

@@ -0,0 +1,123 @@
+'use client';
+
+import clsx from 'clsx';
+import type { Key } from 'react-aria';
+import { OpenAPISelect, OpenAPISelectItem, useSelectState } from './OpenAPISelect';
+import { StaticSection } from './StaticSection';
+import { createStateKey, getStatusCodeClassName } from './utils';
+
+type OpenAPIResponseExampleItem = OpenAPISelectItem & {
+    statusCode: string;
+    body: React.ReactNode;
+};
+
+/**
+ * Get the state of the response examples select.
+ */
+export function useResponseExamplesState(
+    blockKey: string | undefined,
+    initialKey: Key = 'default'
+) {
+    return useSelectState(getResponseExampleStateKey(blockKey), initialKey);
+}
+
+export function OpenAPIResponseExampleContent(props: {
+    items: OpenAPIResponseExampleItem[];
+    blockKey?: string;
+    selectIcon?: React.ReactNode;
+}) {
+    const { blockKey, items, selectIcon } = props;
+
+    return (
+        <StaticSection
+            header={
+                <OpenAPIResponseExampleHeader
+                    selectIcon={selectIcon}
+                    blockKey={blockKey}
+                    items={items}
+                />
+            }
+            className="openapi-response-examples"
+        >
+            <OpenAPIResponseExampleBody blockKey={blockKey} items={items} />
+        </StaticSection>
+    );
+}
+
+function OpenAPIResponseExampleHeader(props: {
+    items: OpenAPIResponseExampleItem[];
+    blockKey?: string;
+    selectIcon?: React.ReactNode;
+}) {
+    const { items, blockKey, selectIcon } = props;
+
+    if (items.length === 1) {
+        const item = items[0];
+
+        if (!item) {
+            return null;
+        }
+
+        return (
+            <span className="openapi-response-examples-statuscode-title">
+                <span
+                    className={clsx(
+                        'openapi-statuscode',
+                        `openapi-statuscode-${getStatusCodeClassName(item.statusCode)}`,
+                        'openapi-response-examples-statuscode'
+                    )}
+                >
+                    {item.statusCode}
+                </span>
+                <span>{item.label}</span>
+            </span>
+        );
+    }
+
+    return (
+        <OpenAPISelect
+            items={items}
+            icon={selectIcon}
+            stateKey={getResponseExampleStateKey(blockKey)}
+            placement="bottom start"
+        >
+            {items.map((item) => (
+                <OpenAPISelectItem key={item.key} id={item.key} value={item}>
+                    <span
+                        className={clsx(
+                            'openapi-statuscode',
+                            `openapi-statuscode-${getStatusCodeClassName(item.statusCode)}`,
+                            'openapi-response-examples-statuscode'
+                        )}
+                    >
+                        {item.statusCode}
+                    </span>
+                    <span>{item.label}</span>
+                </OpenAPISelectItem>
+            ))}
+        </OpenAPISelect>
+    );
+}
+
+function OpenAPIResponseExampleBody(props: {
+    items: OpenAPIResponseExampleItem[];
+    blockKey?: string;
+}) {
+    const { blockKey, items } = props;
+    const state = useResponseExamplesState(blockKey, items[0]?.key);
+
+    const selectedItem = items.find((item) => item.key === state.key) ?? items[0];
+
+    if (!selectedItem) {
+        return null;
+    }
+
+    return <div className="openapi-response-examples-panel">{selectedItem.body}</div>;
+}
+
+/**
+ * Return the state key for the response examples.
+ */
+function getResponseExampleStateKey(blockKey: string | undefined) {
+    return createStateKey('openapi-responses', blockKey);
+}

package/src/OpenAPIResponses.tsx

@@ -1,9 +1,15 @@
+'use client';
+
 import type { OpenAPIV3, OpenAPIV3_1 } from '@gitbook/openapi-parser';
+import clsx from 'clsx';
 import { Markdown } from './Markdown';
 import { OpenAPIDisclosureGroup } from './OpenAPIDisclosureGroup';
 import { OpenAPIResponse } from './OpenAPIResponse';
+import { useResponseExamplesState } from './OpenAPIResponseExampleContent';
 import { StaticSection } from './StaticSection';
-import type { OpenAPIClientContext } from './types';
+import type { OpenAPIClientContext } from './context';
+import { t } from './translate';
+import { createStateKey, getStatusCodeClassName, getStatusCodeDefaultLabel } from './utils';
 
 /**
  * Display an interactive response body.
@@ -14,70 +20,85 @@ export function OpenAPIResponses(props: {
 }) {
     const { responses, context } = props;
 
-    return (
-        <StaticSection header="Responses" className="openapi-responses">
-            <OpenAPIDisclosureGroup
-                allowsMultipleExpanded
-                icon={context.icons.chevronRight}
-                groups={Object.entries(responses).map(
-                    ([statusCode, response]: [string, OpenAPIV3.ResponseObject]) => {
-                        const tabs = (() => {
-                            // If there is no content, but there are headers, we need to show the headers
-                            if (
-                                (!response.content || !Object.keys(response.content).length) &&
-                                response.headers &&
-                                Object.keys(response.headers).length
-                            ) {
-                                return [
-                                    {
-                                        id: 'default',
-                                        body: (
-                                            <OpenAPIResponse
-                                                response={response}
-                                                mediaType={{}}
-                                                context={context}
-                                            />
-                                        ),
-                                    },
-                                ];
-                            }
+    const groups = Object.entries(responses).map(
+        ([statusCode, response]: [string, OpenAPIV3.ResponseObject]) => {
+            const tabs = (() => {
+                // If there is no content, but there are headers, we need to show the headers
+                if (
+                    (!response.content || !Object.keys(response.content).length) &&
+                    response.headers &&
+                    Object.keys(response.headers).length
+                ) {
+                    return [
+                        {
+                            key: 'default',
+                            label: '',
+                            body: (
+                                <OpenAPIResponse
+                                    response={response}
+                                    mediaType={{}}
+                                    context={context}
+                                />
+                            ),
+                        },
+                    ];
+                }
 
-                            return Object.entries(response.content ?? {}).map(
-                                ([contentType, mediaType]) => ({
-                                    id: contentType,
-                                    label: contentType,
-                                    body: (
-                                        <OpenAPIResponse
-                                            response={response}
-                                            mediaType={mediaType}
-                                            context={context}
-                                        />
-                                    ),
-                                })
-                            );
-                        })();
+                return Object.entries(response.content ?? {}).map(([contentType, mediaType]) => ({
+                    key: contentType,
+                    label: contentType,
+                    body: (
+                        <OpenAPIResponse
+                            response={response}
+                            mediaType={mediaType}
+                            context={context}
+                        />
+                    ),
+                }));
+            })();
 
-                        const description = response.description;
+            const description = response.description;
 
-                        return {
-                            id: statusCode,
-                            label: (
-                                <div className="openapi-response-tab-content">
-                                    <span className="openapi-response-statuscode">
-                                        {statusCode}
-                                    </span>
-                                    {description ? (
-                                        <Markdown
-                                            source={description}
-                                            className="openapi-response-description"
-                                        />
-                                    ) : null}
-                                </div>
-                            ),
-                            tabs,
-                        };
-                    }
-                )}
+            return {
+                key: statusCode,
+                label: (
+                    <div className="openapi-response-tab-content">
+                        <span
+                            className={clsx(
+                                'openapi-statuscode',
+                                `openapi-statuscode-${getStatusCodeClassName(statusCode)}`
+                            )}
+                        >
+                            {statusCode}
+                        </span>
+                        {description ? (
+                            <Markdown
+                                source={description}
+                                className="openapi-response-description"
+                            />
+                        ) : (
+                            getStatusCodeDefaultLabel(statusCode, context)
+                        )}
+                    </div>
+                ),
+                tabs,
+            };
+        }
+    );
+
+    const state = useResponseExamplesState(context.blockKey, groups[0]?.key);
+
+    return (
+        <StaticSection header={t(context.translation, 'responses')} className="openapi-responses">
+            <OpenAPIDisclosureGroup
+                icon={context.icons.chevronRight}
+                expandedKeys={state.key ? new Set([state.key]) : new Set()}
+                onExpandedChange={(keys) => {
+                    const key = keys.values().next().value ?? null;
+                    state.setKey(key);
+                }}
+                groups={groups}
+                selectStateKey={createStateKey('response-media-types', context.blockKey)}
             />
         </StaticSection>
     );