@gitbook/react-openapi 1.1.9 → 1.2.0

package/src/OpenAPISpec.tsx

@@ -5,16 +5,23 @@ import { OpenAPIResponses } from './OpenAPIResponses';
 import { OpenAPISchemaProperties } from './OpenAPISchemaServer';
 import { OpenAPISecurities } from './OpenAPISecurities';
 import { StaticSection } from './StaticSection';
-import type { OpenAPIClientContext, OpenAPIOperationData } from './types';
+import type { OpenAPIClientContext } from './context';
+import { tString } from './translate';
+import type { OpenAPIOperationData, OpenAPIWebhookData } from './types';
 import { parameterToProperty } from './utils';
 
-export function OpenAPISpec(props: { data: OpenAPIOperationData; context: OpenAPIClientContext }) {
+export function OpenAPISpec(props: {
+    data: OpenAPIOperationData | OpenAPIWebhookData;
+    context: OpenAPIClientContext;
+}) {
     const { data, context } = props;
 
-    const { operation, securities } = data;
+    const { operation } = data;
 
     const parameters = operation.parameters ?? [];
-    const parameterGroups = groupParameters(parameters);
+    const parameterGroups = groupParameters(parameters, context);
+
+    const securities = 'securities' in data ? data.securities : [];
 
     return (
         <>
@@ -42,6 +49,7 @@ export function OpenAPISpec(props: { data: OpenAPIOperationData; context: OpenAP
                     key="body"
                     requestBody={operation.requestBody}
                     context={context}
+                    data={data}
                 />
             ) : null}
             {operation.responses ? (
@@ -55,7 +63,10 @@ export function OpenAPISpec(props: { data: OpenAPIOperationData; context: OpenAP
     );
 }
 
-function groupParameters(parameters: OpenAPI.Parameters): Array<{
+function groupParameters(
+    parameters: OpenAPI.Parameters,
+    context: OpenAPIClientContext
+): Array<{
     key: string;
     label: string;
     parameters: OpenAPI.Parameters;
@@ -72,7 +83,7 @@ function groupParameters(parameters: OpenAPI.Parameters): Array<{
         .filter((parameter) => parameter.in)
         .forEach((parameter) => {
             const key = parameter.in;
-            const label = getParameterGroupName(parameter.in);
+            const label = getParameterGroupName(parameter.in, context);
             const group = groups.find((group) => group.key === key);
             if (group) {
                 group.parameters.push(parameter);
@@ -90,14 +101,14 @@ function groupParameters(parameters: OpenAPI.Parameters): Array<{
     return groups;
 }
 
-function getParameterGroupName(paramIn: string): string {
+function getParameterGroupName(paramIn: string, context: OpenAPIClientContext): string {
     switch (paramIn) {
         case 'path':
-            return 'Path parameters';
+            return tString(context.translation, 'path_parameters');
         case 'query':
-            return 'Query parameters';
+            return tString(context.translation, 'query_parameters');
         case 'header':
-            return 'Header parameters';
+            return tString(context.translation, 'header_parameters');
         default:
             return paramIn;
     }

package/src/OpenAPITabs.tsx

@@ -3,7 +3,7 @@
 import { createContext, useContext, useEffect, useMemo, useRef, useState } from 'react';
 import { type Key, Tab, TabList, TabPanel, Tabs, type TabsProps } from 'react-aria-components';
 import { useEventCallback } from 'usehooks-ts';
-import { getOrCreateTabStoreByKey } from './useSyncedTabsGlobalState';
+import { getOrCreateStoreByKey } from './getOrCreateStoreByKey';
 
 export type TabItem = {
     key: Key;
@@ -36,8 +36,8 @@ export function OpenAPITabs(
     const { children, items, stateKey } = props;
     const [tabKey, setTabKey] = useState<Key | null>(() => {
         if (stateKey && typeof window !== 'undefined') {
-            const store = getOrCreateTabStoreByKey(stateKey);
-            const tabKey = store.getState().tabKey;
+            const store = getOrCreateStoreByKey(stateKey);
+            const tabKey = store.getState().key;
             if (tabKey) {
                 return tabKey;
             }
@@ -60,10 +60,10 @@ export function OpenAPITabs(
         if (!stateKey) {
             return undefined;
         }
-        const store = getOrCreateTabStoreByKey(stateKey);
+        const store = getOrCreateStoreByKey(stateKey);
         return store.subscribe((state) => {
             cancelDeferRef.current?.();
-            cancelDeferRef.current = defer(() => selectTab(state.tabKey));
+            cancelDeferRef.current = defer(() => selectTab(state.key));
         });
     }, [stateKey, selectTab]);
     useEffect(() => {
@@ -77,8 +77,8 @@ export function OpenAPITabs(
                 onSelectionChange={(tabKey) => {
                     selectTab(tabKey);
                     if (stateKey) {
-                        const store = getOrCreateTabStoreByKey(stateKey);
-                        store.setState({ tabKey });
+                        const store = getOrCreateStoreByKey(stateKey);
+                        store.setState({ key: tabKey });
                     }
                 }}
                 selectedKey={tabKey}
@@ -138,9 +138,9 @@ export function OpenAPITabsPanels() {
 
     return (
         <TabPanel id={key} className="openapi-tabs-panel">
-            <div className="openapi-tabs-body">{selectedTab.body}</div>
+            <div className="openapi-panel-body">{selectedTab.body}</div>
             {selectedTab.footer ? (
-                <div className="openapi-tabs-footer">{selectedTab.footer}</div>
+                <div className="openapi-panel-footer">{selectedTab.footer}</div>
             ) : null}
         </TabPanel>
     );

package/src/OpenAPIWebhook.tsx

@@ -0,0 +1,33 @@
+import clsx from 'clsx';
+import { OpenAPIWebhookExample } from './OpenAPIWebhookExample';
+import { OpenAPIColumnSpec } from './common/OpenAPIColumnSpec';
+import { OpenAPISummary } from './common/OpenAPISummary';
+import { type OpenAPIContextInput, resolveOpenAPIContext } from './context';
+import type { OpenAPIWebhookData } from './types';
+
+/**
+ * Display an interactive OpenAPI webhook.
+ */
+export function OpenAPIWebhook(props: {
+    className?: string;
+    data: OpenAPIWebhookData;
+    context: OpenAPIContextInput;
+}) {
+    const { className, data, context: contextInput } = props;
+
+    const context = resolveOpenAPIContext(contextInput);
+
+    return (
+        <div className={clsx('openapi-webhook', className)}>
+            <OpenAPISummary data={data} context={context} />
+            <div className="openapi-columns">
+                <OpenAPIColumnSpec data={data} context={context} />
+                <div className="openapi-column-preview">
+                    <div className="openapi-column-preview-body">
+                        <OpenAPIWebhookExample data={data} context={context} />
+                    </div>
+                </div>
+            </div>
+        </div>
+    );
+}

package/src/OpenAPIWebhookExample.tsx

@@ -0,0 +1,60 @@
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import { OpenAPIEmptyExample } from './OpenAPIExample';
+import { OpenAPIMediaTypeContent } from './OpenAPIMediaType';
+import { type OpenAPIContext, getOpenAPIClientContext } from './context';
+import type { OpenAPIWebhookData } from './types';
+import { getExamples } from './util/example';
+import { createStateKey } from './utils';
+
+export function OpenAPIWebhookExample(props: {
+    data: OpenAPIWebhookData;
+    context: OpenAPIContext;
+}) {
+    const { data, context } = props;
+    const { operation } = data;
+
+    const items = (() => {
+        if (!operation.requestBody) {
+            return [];
+        }
+
+        return Object.entries(
+            operation.requestBody.content as Record<string, OpenAPIV3.MediaTypeObject>
+        ).map(([key, value]) => {
+            const schema = value.schema;
+
+            if (!schema) {
+                return {
+                    key,
+                    label: key,
+                    body: <OpenAPIEmptyExample context={context} />,
+                };
+            }
+
+            return {
+                key,
+                label: key,
+                body: <></>,
+                examples: getExamples({
+                    mediaTypeObject: value,
+                    mediaType: key,
+                    context,
+                }),
+            };
+        });
+    })();
+
+    return (
+        <div className="openapi-panel">
+            <h4 className="openapi-panel-heading">Payload</h4>
+            <div className="openapi-panel-body">
+                <OpenAPIMediaTypeContent
+                    selectIcon={context.icons.chevronDown}
+                    stateKey={createStateKey('request-body-media-type', context.blockKey)}
+                    items={items}
+                    context={getOpenAPIClientContext(context)}
+                />
+            </div>
+        </div>
+    );
+}

package/src/ScalarApiButton.tsx

@@ -6,6 +6,8 @@ import { createPortal } from 'react-dom';
 
 import type { OpenAPIV3_1 } from '@gitbook/openapi-parser';
 import { useOpenAPIOperationContext } from './OpenAPIOperationContext';
+import type { OpenAPIClientContext } from './context';
+import { t } from './translate';
 
 /**
  * Button which launches the Scalar API Client
@@ -14,8 +16,9 @@ export function ScalarApiButton(props: {
     method: OpenAPIV3_1.HttpMethods;
     path: string;
     specUrl: string;
+    context: OpenAPIClientContext;
 }) {
-    const { method, path, specUrl } = props;
+    const { method, path, specUrl, context } = props;
     const [isOpen, setIsOpen] = useState(false);
     const controllerRef = useRef<ScalarModalControllerRef>(null);
     return (
@@ -27,7 +30,7 @@ export function ScalarApiButton(props: {
                     setIsOpen(true);
                 }}
             >
-                Test it
+                {t(context.translation, 'test_it')}
                 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 12" fill="currentColor">
                     <path
                         stroke="currentColor"
@@ -59,10 +62,7 @@ function ScalarModal(props: {
 }) {
     const { method, path, specUrl, controllerRef } = props;
     return (
-        <ApiClientModalProvider
-            configuration={{ spec: { url: specUrl } }}
-            initialRequest={{ method, path }}
-        >
+        <ApiClientModalProvider configuration={{ url: specUrl }} initialRequest={{ method, path }}>
             <ScalarModalController method={method} path={path} controllerRef={controllerRef} />
         </ApiClientModalProvider>
     );

package/src/StaticSection.tsx

@@ -42,18 +42,50 @@ export const SectionBody = forwardRef(function SectionBody(
     );
 });
 
+export function SectionFooter(props: ComponentPropsWithoutRef<'div'>) {
+    return (
+        <div
+            {...props}
+            className={clsx(
+                'openapi-section-footer',
+                props.className && `${props.className}-footer`
+            )}
+        />
+    );
+}
+
+export function SectionFooterContent(props: ComponentPropsWithoutRef<'div'>) {
+    return (
+        <div
+            {...props}
+            className={clsx(
+                'openapi-section-footer-content',
+                props.className && `${props.className}-footer-content`
+            )}
+        />
+    );
+}
+
 export function StaticSection(props: {
     className: string;
-    header: React.ReactNode;
+    header?: React.ReactNode;
     children: React.ReactNode;
+    footer?: React.ReactNode;
 }) {
-    const { className, header, children } = props;
+    const { className, header, children, footer } = props;
     return (
         <Section className={className}>
-            <SectionHeader className={className}>
-                <SectionHeaderContent className={className}>{header}</SectionHeaderContent>
-            </SectionHeader>
+            {header ? (
+                <SectionHeader className={className}>
+                    <SectionHeaderContent className={className}>{header}</SectionHeaderContent>
+                </SectionHeader>
+            ) : null}
             <SectionBody className={className}>{children}</SectionBody>
+            {footer ? (
+                <SectionFooter className={className}>
+                    <SectionFooterContent className={className}>{footer}</SectionFooterContent>
+                </SectionFooter>
+            ) : null}
         </Section>
     );
 }

package/src/code-samples.test.ts

@@ -413,13 +413,15 @@ describe('python code sample generator', () => {
             },
             body: {
                 key: 'value',
+                truethy: true,
+                falsey: false,
             },
         };
 
         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={"key":"value"}\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})\n)\n\ndata = response.json()'
         );
     });
 

package/src/code-samples.ts

@@ -3,6 +3,7 @@ import {
     isFormData,
     isFormUrlEncoded,
     isGraphQL,
+    isJSON,
     isPDF,
     isPlainObject,
     isText,
@@ -26,6 +27,52 @@ export interface CodeSampleGenerator {
 }
 
 export const codeSampleGenerators: CodeSampleGenerator[] = [
+    {
+        id: 'http',
+        label: 'HTTP',
+        syntax: 'bash',
+        generate: ({ method, url, headers = {}, body }: CodeSampleInput) => {
+            const { host, path } = parseHostAndPath(url);
+
+            if (body) {
+                // if we had a body add a content length header
+                const bodyContent = body ? stringifyOpenAPI(body) : '';
+                // handle unicode chars with a text encoder
+                const encoder = new TextEncoder();
+
+                const bodyString = BodyGenerators.getHTTPBody(body, headers);
+
+                if (bodyString) {
+                    body = bodyString;
+                }
+
+                headers = {
+                    ...headers,
+                    'Content-Length': encoder.encode(bodyContent).length.toString(),
+                };
+            }
+
+            if (!headers.hasOwnProperty('Accept')) {
+                headers.Accept = '*/*';
+            }
+
+            const headerString = headers
+                ? `${Object.entries(headers)
+                      .map(([key, value]) =>
+                          key.toLowerCase() !== 'host' ? `${key}: ${value}` : ''
+                      )
+                      .join('\n')}\n`
+                : '';
+
+            const bodyString = body ? `\n${body}` : '';
+
+            const httpRequest = `${method.toUpperCase()} ${decodeURI(path)} HTTP/1.1
+Host: ${host}
+${headerString}${bodyString}`;
+
+            return httpRequest;
+        },
+    },
     {
         id: 'curl',
         label: 'cURL',
@@ -127,11 +174,14 @@ export const codeSampleGenerators: CodeSampleGenerator[] = [
                 code += indent(`headers=${stringifyOpenAPI(headers)},\n`, 4);
             }
 
+            const contentType = headers?.['Content-Type'];
             if (body) {
                 if (body === 'files') {
                     code += indent(`files=${body}\n`, 4);
+                } else if (isJSON(contentType)) {
+                    code += indent(`data=json.dumps(${body})\n`, 4);
                 } else {
-                    code += indent(`data=${stringifyOpenAPI(body)}\n`, 4);
+                    code += indent(`data=${body}\n`, 4);
                 }
             }
 
@@ -140,52 +190,6 @@ export const codeSampleGenerators: CodeSampleGenerator[] = [
             return code;
         },
     },
-    {
-        id: 'http',
-        label: 'HTTP',
-        syntax: 'bash',
-        generate: ({ method, url, headers = {}, body }: CodeSampleInput) => {
-            const { host, path } = parseHostAndPath(url);
-
-            if (body) {
-                // if we had a body add a content length header
-                const bodyContent = body ? stringifyOpenAPI(body) : '';
-                // handle unicode chars with a text encoder
-                const encoder = new TextEncoder();
-
-                const bodyString = BodyGenerators.getHTTPBody(body, headers);
-
-                if (bodyString) {
-                    body = bodyString;
-                }
-
-                headers = {
-                    ...headers,
-                    'Content-Length': encoder.encode(bodyContent).length.toString(),
-                };
-            }
-
-            if (!headers.hasOwnProperty('Accept')) {
-                headers.Accept = '*/*';
-            }
-
-            const headerString = headers
-                ? `${Object.entries(headers)
-                      .map(([key, value]) =>
-                          key.toLowerCase() !== 'host' ? `${key}: ${value}` : ''
-                      )
-                      .join('\n')}\n`
-                : '';
-
-            const bodyString = body ? `\n${body}` : '';
-
-            const httpRequest = `${method.toUpperCase()} ${decodeURI(path)} HTTP/1.1
-Host: ${host}
-${headerString}${bodyString}`;
-
-            return httpRequest;
-        },
-    },
 ];
 
 function indent(code: string, spaces: number) {
@@ -343,18 +347,27 @@ const BodyGenerators = {
             }
             code += '}\n\n';
             body = 'files';
-        }
-
-        if (isPDF(contentType)) {
+        } else if (isPDF(contentType)) {
             code += 'files = {\n';
             code += `${indent(`"file": "${body}",`, 4)}\n`;
             code += '}\n\n';
             body = 'files';
-        }
-
-        if (isXML(contentType)) {
+        } else if (isXML(contentType)) {
             // Convert JSON to XML if needed
-            body = convertBodyToXML(body);
+            body = JSON.stringify(convertBodyToXML(body));
+        } else {
+            body = stringifyOpenAPI(body, (_key, value) => {
+                switch (value) {
+                    case true:
+                        return '$$__TRUE__$$';
+                    case false:
+                        return '$$__FALSE__$$';
+                    default:
+                        return value;
+                }
+            })
+                .replaceAll('"$$__TRUE__$$"', 'True')
+                .replaceAll('"$$__FALSE__$$"', 'False');
         }
 
         return { body, code, headers };

package/src/common/OpenAPIColumnSpec.tsx

@@ -0,0 +1,31 @@
+import { OpenAPISpec } from '../OpenAPISpec';
+import { type OpenAPIContext, getOpenAPIClientContext } from '../context';
+import { t } from '../translate';
+import type { OpenAPIOperationData, OpenAPIWebhookData } from '../types';
+import { OpenAPIOperationDescription } from './OpenAPIOperationDescription';
+
+export function OpenAPIColumnSpec(props: {
+    data: OpenAPIOperationData | OpenAPIWebhookData;
+    context: OpenAPIContext;
+}) {
+    const { data, context } = props;
+    const { operation } = data;
+
+    const clientContext = getOpenAPIClientContext(context);
+
+    return (
+        <div className="openapi-column-spec">
+            {operation['x-deprecated-sunset'] ? (
+                <div className="openapi-deprecated-sunset openapi-description openapi-markdown">
+                    {t(context.translation, 'deprecated_and_sunset_on', [
+                        <span key="date" className="openapi-deprecated-sunset-date">
+                            {operation['x-deprecated-sunset']}
+                        </span>,
+                    ])}
+                </div>
+            ) : null}
+            <OpenAPIOperationDescription operation={operation} context={context} />
+            <OpenAPISpec data={data} context={clientContext} />
+        </div>
+    );
+}

package/src/common/OpenAPIOperationDescription.tsx

@@ -0,0 +1,31 @@
+import type { OpenAPICustomOperationProperties, OpenAPIV3 } from '@gitbook/openapi-parser';
+import { Markdown } from '../Markdown';
+import type { OpenAPIContext } from '../context';
+import { resolveDescription } from '../utils';
+
+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/common/OpenAPIStability.tsx

@@ -0,0 +1,23 @@
+import type { OpenAPIStability as OpenAPIStabilityType } from '@gitbook/openapi-parser';
+
+const stabilityEnum: Record<OpenAPIStabilityType, string> = {
+    experimental: 'Experimental',
+    alpha: 'Alpha',
+    beta: 'Beta',
+} as const;
+
+export function OpenAPIStability(props: { stability: OpenAPIStabilityType }) {
+    const { stability } = props;
+
+    const foundStability = stabilityEnum[stability];
+
+    if (!foundStability) {
+        return null;
+    }
+
+    return (
+        <div className={`openapi-stability openapi-stability-${foundStability.toLowerCase()}`}>
+            {foundStability}
+        </div>
+    );
+}

package/src/common/OpenAPISummary.tsx

@@ -0,0 +1,45 @@
+import { OpenAPIPath } from '../OpenAPIPath';
+import type { OpenAPIContext } from '../context';
+import type { OpenAPIOperationData, OpenAPIWebhookData } from '../types';
+import { OpenAPIStability } from './OpenAPIStability';
+
+export function OpenAPISummary(props: {
+    data: OpenAPIOperationData | OpenAPIWebhookData;
+    context: OpenAPIContext;
+}) {
+    const { data, context } = props;
+    const { operation } = data;
+
+    const title = (() => {
+        if (operation.summary) {
+            return operation.summary;
+        }
+
+        if ('name' in data) {
+            return data.name;
+        }
+
+        return undefined;
+    })();
+
+    return (
+        <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'] && (
+                        <OpenAPIStability stability={operation['x-stability']} />
+                    )}
+                </div>
+            )}
+            {title
+                ? context.renderHeading({
+                      deprecated: operation.deprecated ?? false,
+                      stability: operation['x-stability'],
+                      title,
+                  })
+                : null}
+            {'path' in data ? <OpenAPIPath data={data} context={context} /> : null}
+        </div>
+    );
+}