@gitbook/react-openapi 1.1.9 → 1.2.0

package/src/OpenAPIMediaType.tsx

@@ -0,0 +1,139 @@
+'use client';
+
+import type { Key } from 'react-aria';
+import { OpenAPIEmptyExample } from './OpenAPIExample';
+import { OpenAPISelect, OpenAPISelectItem, useSelectState } from './OpenAPISelect';
+import { StaticSection } from './StaticSection';
+import type { OpenAPIClientContext } from './context';
+
+type OpenAPIMediaTypeItem = OpenAPISelectItem & {
+    body: React.ReactNode;
+    examples?: OpenAPIMediaTypeItem[];
+};
+
+/**
+ * Get the state of the response examples select.
+ */
+export function useMediaTypesState(stateKey: string | undefined, initialKey: Key = 'default') {
+    return useSelectState(stateKey, initialKey);
+}
+
+function useMediaTypeExamplesState(stateKey: string | undefined, initialKey: Key = 'default') {
+    return useSelectState(stateKey, initialKey);
+}
+
+export function OpenAPIMediaTypeContent(props: {
+    items: OpenAPIMediaTypeItem[];
+    selectIcon?: React.ReactNode;
+    stateKey: string;
+    context: OpenAPIClientContext;
+}) {
+    const { stateKey, items, selectIcon, context } = props;
+    const state = useMediaTypesState(stateKey, items[0]?.key);
+
+    const examples = items.find((item) => item.key === state.key)?.examples ?? [];
+
+    if (!items.length && !examples.length) {
+        return null;
+    }
+
+    return (
+        <StaticSection
+            footer={
+                items.length > 1 || examples.length > 1 ? (
+                    <OpenAPIMediaTypeFooter
+                        items={items}
+                        examples={examples}
+                        selectIcon={selectIcon}
+                        stateKey={stateKey}
+                    />
+                ) : null
+            }
+            className="openapi-response-media-types-examples"
+        >
+            <OpenAPIMediaTypeBody
+                context={context}
+                stateKey={stateKey}
+                items={items}
+                examples={examples}
+            />
+        </StaticSection>
+    );
+}
+
+function OpenAPIMediaTypeFooter(props: {
+    items: OpenAPIMediaTypeItem[];
+    examples?: OpenAPIMediaTypeItem[];
+    selectIcon?: React.ReactNode;
+    stateKey: string;
+}) {
+    const { items, examples, stateKey, selectIcon } = props;
+
+    return (
+        <>
+            {items.length > 1 && (
+                <OpenAPISelect
+                    icon={selectIcon}
+                    items={items}
+                    stateKey={stateKey}
+                    placement="bottom start"
+                >
+                    {items.map((item) => (
+                        <OpenAPISelectItem key={item.key} id={item.key} value={item}>
+                            <span>{item.label}</span>
+                        </OpenAPISelectItem>
+                    ))}
+                </OpenAPISelect>
+            )}
+
+            {examples && examples.length > 1 ? (
+                <OpenAPISelect
+                    icon={selectIcon}
+                    items={examples}
+                    stateKey={`${stateKey}-examples`}
+                    placement="bottom start"
+                >
+                    {examples.map((example) => (
+                        <OpenAPISelectItem key={example.key} id={example.key} value={example}>
+                            <span>{example.label}</span>
+                        </OpenAPISelectItem>
+                    ))}
+                </OpenAPISelect>
+            ) : null}
+        </>
+    );
+}
+
+function OpenAPIMediaTypeBody(props: {
+    items: OpenAPIMediaTypeItem[];
+    examples?: OpenAPIMediaTypeItem[];
+    stateKey: string;
+    context: OpenAPIClientContext;
+}) {
+    const { stateKey, items, examples, context } = props;
+    const state = useMediaTypesState(stateKey, items[0]?.key);
+
+    const selectedItem = items.find((item) => item.key === state.key) ?? items[0];
+
+    const exampleState = useMediaTypeExamplesState(
+        `${stateKey}-examples`,
+        selectedItem?.examples?.[0]?.key
+    );
+
+    if (!selectedItem) {
+        return null;
+    }
+
+    if (examples) {
+        const selectedExample =
+            examples.find((example) => example.key === exampleState.key) ?? examples[0];
+
+        if (!selectedExample) {
+            return <OpenAPIEmptyExample context={context} />;
+        }
+
+        return selectedExample.body;
+    }
+
+    return selectedItem.body;
+}

package/src/OpenAPIOperation.tsx

@@ -1,17 +1,10 @@
 import clsx from 'clsx';
-
-import type {
-    OpenAPICustomOperationProperties,
-    OpenAPIStability,
-    OpenAPIV3,
-} from '@gitbook/openapi-parser';
-import { Markdown } from './Markdown';
 import { OpenAPICodeSample } from './OpenAPICodeSample';
-import { OpenAPIPath } from './OpenAPIPath';
 import { OpenAPIResponseExample } from './OpenAPIResponseExample';
-import { OpenAPISpec } from './OpenAPISpec';
-import type { OpenAPIClientContext, OpenAPIContextProps, OpenAPIOperationData } from './types';
-import { resolveDescription } from './utils';
+import { OpenAPIColumnSpec } from './common/OpenAPIColumnSpec';
+import { OpenAPISummary } from './common/OpenAPISummary';
+import { type OpenAPIContextInput, resolveOpenAPIContext } from './context';
+import type { OpenAPIOperationData } from './types';
 
 /**
  * Display an interactive OpenAPI operation.
@@ -19,110 +12,24 @@ import { resolveDescription } from './utils';
 export function OpenAPIOperation(props: {
     className?: string;
     data: OpenAPIOperationData;
-    context: OpenAPIContextProps;
+    context: OpenAPIContextInput;
 }) {
-    const { className, data, context } = props;
-    const { operation } = data;
+    const { className, data, context: contextInput } = props;
 
-    const clientContext: OpenAPIClientContext = {
-        defaultInteractiveOpened: context.defaultInteractiveOpened,
-        icons: context.icons,
-        blockKey: context.blockKey,
-    };
+    const context = resolveOpenAPIContext(contextInput);
 
     return (
         <div className={clsx('openapi-operation', className)}>
-            <div className="openapi-summary" id={operation.summary ? undefined : context.id}>
-                {(operation.deprecated || operation['x-stability']) && (
-                    <div className="openapi-summary-tags">
-                        {operation.deprecated && (
-                            <div className="openapi-deprecated">Deprecated</div>
-                        )}
-                        {operation['x-stability'] && (
-                            <OpenAPIOperationStability stability={operation['x-stability']} />
-                        )}
-                    </div>
-                )}
-                {operation.summary
-                    ? context.renderHeading({
-                          deprecated: operation.deprecated ?? false,
-                          stability: operation['x-stability'],
-                          title: operation.summary,
-                      })
-                    : null}
-                <OpenAPIPath data={data} context={context} />
-            </div>
+            <OpenAPISummary data={data} context={context} />
             <div className="openapi-columns">
-                <div className="openapi-column-spec">
-                    {operation['x-deprecated-sunset'] ? (
-                        <div className="openapi-deprecated-sunset openapi-description openapi-markdown">
-                            This operation is deprecated and will be sunset on{' '}
-                            <span className="openapi-deprecated-sunset-date">
-                                {operation['x-deprecated-sunset']}
-                            </span>
-                            {'.'}
-                        </div>
-                    ) : null}
-                    <OpenAPIOperationDescription operation={operation} context={context} />
-                    <OpenAPISpec data={data} context={clientContext} />
-                </div>
+                <OpenAPIColumnSpec data={data} context={context} />
                 <div className="openapi-column-preview">
                     <div className="openapi-column-preview-body">
-                        <OpenAPICodeSample {...props} />
-                        <OpenAPIResponseExample {...props} />
+                        <OpenAPICodeSample data={data} context={context} />
+                        <OpenAPIResponseExample data={data} context={context} />
                     </div>
                 </div>
             </div>
         </div>
     );
 }
-
-function OpenAPIOperationDescription(props: {
-    operation: OpenAPIV3.OperationObject<OpenAPICustomOperationProperties>;
-    context: OpenAPIContextProps;
-}) {
-    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>
-    );
-}
-
-const stabilityEnum = {
-    experimental: 'Experimental',
-    alpha: 'Alpha',
-    beta: 'Beta',
-    stable: 'Stable',
-} as const;
-
-function OpenAPIOperationStability(props: { stability: OpenAPIStability }) {
-    const { stability } = props;
-
-    const foundStability = stabilityEnum[stability];
-
-    if (!foundStability) {
-        return null;
-    }
-
-    return (
-        <div className={`openapi-stability openapi-stability-${foundStability.toLowerCase()}`}>
-            {foundStability}
-        </div>
-    );
-}

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,5 +1,6 @@
 import { OpenAPICopyButton } from './OpenAPICopyButton';
-import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
+import { type OpenAPIUniversalContext, getOpenAPIClientContext } from './context';
+import type { OpenAPIOperationData } from './types';
 import { getDefaultServerURL } from './util/server';
 
 /**
@@ -7,25 +8,44 @@ import { getDefaultServerURL } from './util/server';
  */
 export function OpenAPIPath(props: {
     data: OpenAPIOperationData;
-    context: OpenAPIContextProps;
+    context: OpenAPIUniversalContext;
+    /** Whether to show the server URL.
+     * @default true
+     */
+    withServer?: boolean;
+    /**
+     * Whether the path is copyable.
+     * @default true
+     */
+    canCopy?: boolean;
 }) {
-    const { data } = props;
+    const { data, context, withServer = true, canCopy = true } = props;
     const { method, path, operation } = data;
 
     const server = getDefaultServerURL(data.servers);
     const formattedPath = formatPath(path);
 
+    const element = (() => {
+        return (
+            <>
+                {withServer ? <span className="openapi-path-server">{server}</span> : null}
+                {formattedPath}
+            </>
+        );
+    })();
+
     return (
         <div className="openapi-path">
             <div className={`openapi-method openapi-method-${method}`}>{method}</div>
 
             <OpenAPICopyButton
-                value={server + path}
+                value={`${withServer ? server : ''}${path}`}
                 className="openapi-path-title"
                 data-deprecated={operation.deprecated}
+                isDisabled={!canCopy}
+                context={getOpenAPIClientContext(context)}
             >
-                <span className="openapi-path-server">{server}</span>
-                {formattedPath}
+                {element}
             </OpenAPICopyButton>
         </div>
     );

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 })