@gitbook/react-openapi 1.1.10 → 1.2.0

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

package/src/context.ts

@@ -1,4 +1,11 @@
+import { type Translation, type TranslationLocale, translations } from './translations';
+
 export interface OpenAPIClientContext {
+    /**
+     * The translation language to use.
+     */
+    translation: Translation;
+
     /**
      * Icons used in the block.
      */
@@ -23,9 +30,14 @@ export interface OpenAPIClientContext {
      * Optional id attached to the heading and used as an anchor.
      */
     id?: string;
+
+    /**
+     * Mark the context as a client context.
+     */
+    $$isClientContext$$: true;
 }
 
-export interface OpenAPIContext extends OpenAPIClientContext {
+export interface OpenAPIContext extends Omit<OpenAPIClientContext, '$$isClientContext$$'> {
     /**
      * Render a code block.
      */
@@ -51,14 +63,37 @@ export interface OpenAPIContext extends OpenAPIClientContext {
     specUrl: string;
 }
 
+export type OpenAPIUniversalContext = OpenAPIClientContext | OpenAPIContext;
+
+export interface OpenAPIContextInput extends Omit<OpenAPIContext, 'translation'> {
+    /**
+     * The translation language to use.
+     * @default 'en'
+     */
+    locale?: TranslationLocale | undefined;
+}
+
+/**
+ * Resolve OpenAPI context from the input.
+ */
+export function resolveOpenAPIContext(context: OpenAPIContextInput): OpenAPIContext {
+    const { locale, ...rest } = context;
+    return {
+        ...rest,
+        translation: translations[locale ?? 'en'],
+    };
+}
+
 /**
  * Get the client context from the OpenAPI context.
  */
-export function getOpenAPIClientContext(context: OpenAPIContext): OpenAPIClientContext {
+export function getOpenAPIClientContext(context: OpenAPIUniversalContext): OpenAPIClientContext {
     return {
+        translation: context.translation,
         icons: context.icons,
         defaultInteractiveOpened: context.defaultInteractiveOpened,
         blockKey: context.blockKey,
         id: context.id,
+        $$isClientContext$$: true,
     };
 }

package/src/getOrCreateStoreByKey.ts

@@ -1,5 +1,3 @@
-'use client';
-
 import { createStore } from 'zustand';
 
 type Key = string | number;
@@ -10,7 +8,7 @@ type State = {
 
 type Actions = { setKey: (key: Key | null) => void };
 
-type Store = State & Actions;
+export type Store = State & Actions;
 
 const createStateStore = (initial?: Key) => {
     return createStore<Store>()((set) => ({

package/src/index.ts

@@ -1,5 +1,9 @@
 export * from './schemas';
 export * from './OpenAPIOperation';
+export * from './OpenAPIWebhook';
 export * from './OpenAPIOperationContext';
 export * from './resolveOpenAPIOperation';
-export type { OpenAPIOperationData, OpenAPIContext } from './types';
+export * from './resolveOpenAPIWebhook';
+export type { OpenAPIOperationData, OpenAPIWebhookData } from './types';
+export type { OpenAPIContextInput } from './context';
+export { checkIsValidLocale } from './translations';