@gitbook/react-openapi 0.7.1 → 1.0.1

package/src/OpenAPIOperationContext.tsx

@@ -0,0 +1,45 @@
+'use client';
+
+import { createContext, useContext, useMemo } from 'react';
+import { useEventCallback } from 'usehooks-ts';
+
+interface OpenAPIOperationPointer {
+    path: string;
+    method: string;
+}
+
+interface OpenAPIOperationContextValue {
+    onOpenClient: (pointer: OpenAPIOperationPointer) => void;
+}
+
+const OpenAPIOperationContext = createContext<OpenAPIOperationContextValue>({
+    onOpenClient: () => {},
+});
+
+/**
+ * Provider for the OpenAPIOperationContext.
+ */
+export function OpenAPIOperationContextProvider(
+    props: React.PropsWithChildren<Partial<OpenAPIOperationContextValue>>,
+) {
+    const { children } = props;
+
+    const onOpenClient = useEventCallback((pointer: OpenAPIOperationPointer) => {
+        props.onOpenClient?.(pointer);
+    });
+
+    const value = useMemo(() => ({ onOpenClient }), [onOpenClient]);
+
+    return (
+        <OpenAPIOperationContext.Provider value={value}>
+            {children}
+        </OpenAPIOperationContext.Provider>
+    );
+}
+
+/**
+ * Hook to access the OpenAPIOperationContext.
+ */
+export function useOpenAPIOperationContext() {
+    return useContext(OpenAPIOperationContext);
+}

package/src/OpenAPIPath.tsx

@@ -0,0 +1,65 @@
+import { ScalarApiButton } from './ScalarApiButton';
+import type { OpenAPIOperationData, OpenAPIContextProps } from './types';
+
+/**
+ * Display the path of an operation.
+ */
+export function OpenAPIPath(props: {
+    data: OpenAPIOperationData;
+    context: OpenAPIContextProps;
+}): JSX.Element {
+    const { data, context } = props;
+    const { method, path } = data;
+    const { specUrl } = context;
+
+    return (
+        <div className="openapi-path">
+            <div className={`openapi-method openapi-method-${method}`}>{method}</div>
+            <div className="openapi-path-title" data-deprecated={data.operation.deprecated}>
+                <p>{formatPath(path)}</p>
+            </div>
+            {data['x-hideTryItPanel'] || data.operation['x-hideTryItPanel'] ? null : (
+                <ScalarApiButton method={method} path={path} specUrl={specUrl} />
+            )}
+        </div>
+    );
+}
+
+// Format the path to highlight placeholders
+function formatPath(path: string) {
+    // Matches placeholders like {id}, {userId}, etc.
+    const regex = /\{(\w+)\}/g;
+
+    const parts: (string | JSX.Element)[] = [];
+    let lastIndex = 0;
+
+    // Replace placeholders with <em> tags
+    path.replace(regex, (match, key, offset) => {
+        parts.push(path.slice(lastIndex, offset));
+        parts.push(<em key={key}>{`{${key}}`}</em>);
+        lastIndex = offset + match.length;
+        return match;
+    });
+
+    // Push remaining text after the last placeholder
+    parts.push(path.slice(lastIndex));
+
+    // Join parts with separators wrapped in <span>
+    const formattedPath = parts.reduce(
+        (acc, part, index) => {
+            if (typeof part === 'string' && index > 0 && part === '/') {
+                return [
+                    ...acc,
+                    <span className="openapi-path-separator" key={`sep-${index}`}>
+                        /
+                    </span>,
+                    part,
+                ];
+            }
+            return [...acc, part];
+        },
+        [] as (string | JSX.Element)[],
+    );
+
+    return <span>{formattedPath}</span>;
+}

package/src/OpenAPIRequestBody.tsx

@@ -1,21 +1,22 @@
-import * as React from 'react';
-
-import { OpenAPIV3 } from 'openapi-types';
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import { OpenAPIRootSchema } from './OpenAPISchema';
-import { noReference } from './utils';
-import { OpenAPIClientContext } from './types';
+import type { OpenAPIClientContext } from './types';
 import { InteractiveSection } from './InteractiveSection';
-import { Markdown } from './Markdown';
+import { checkIsReference } from './utils';
 
 /**
  * Display an interactive request body.
  */
 export function OpenAPIRequestBody(props: {
-    requestBody: OpenAPIV3.RequestBodyObject;
+    requestBody: OpenAPIV3.RequestBodyObject | OpenAPIV3.ReferenceObject;
     context: OpenAPIClientContext;
 }) {
     const { requestBody, context } = props;
 
+    if (checkIsReference(requestBody)) {
+        return null;
+    }
+
     return (
         <InteractiveSection
             header="Body"
@@ -27,21 +28,13 @@ export function OpenAPIRequestBody(props: {
                         label: contentType,
                         body: (
                             <OpenAPIRootSchema
-                                schema={noReference(mediaTypeObject.schema) ?? {}}
+                                schema={mediaTypeObject.schema ?? {}}
                                 context={context}
                             />
                         ),
                     };
                 },
             )}
-            defaultOpened={context.defaultInteractiveOpened}
-        >
-            {requestBody.description ? (
-                <Markdown
-                    source={requestBody.description}
-                    className="openapi-requestbody-description"
-                />
-            ) : null}
-        </InteractiveSection>
+        />
     );
 }

package/src/OpenAPIResponse.tsx

@@ -1,72 +1,54 @@
-import * as React from 'react';
-import classNames from 'classnames';
-import { OpenAPIV3 } from 'openapi-types';
-import { OpenAPIRootSchema, OpenAPISchemaProperties } from './OpenAPISchema';
-import { noReference } from './utils';
-import { OpenAPIClientContext } from './types';
-import { InteractiveSection } from './InteractiveSection';
-import { Markdown } from './Markdown';
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import { OpenAPISchemaProperties } from './OpenAPISchema';
+import { resolveDescription } from './utils';
+import type { OpenAPIClientContext } from './types';
+import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 
 /**
  * Display an interactive response body.
  */
 export function OpenAPIResponse(props: {
     response: OpenAPIV3.ResponseObject;
+    mediaType: OpenAPIV3.MediaTypeObject;
     context: OpenAPIClientContext;
 }) {
-    const { response, context } = props;
-    const content = Object.entries(response.content ?? {});
+    const { response, context, mediaType } = props;
     const headers = Object.entries(response.headers ?? {}).map(
-        ([name, header]) => [name, noReference(header) ?? {}] as const,
+        ([name, header]) => [name, header ?? {}] as const,
     );
+    const content = Object.entries(mediaType.schema ?? {});
 
-    if (content.length === 0 && !response.description && headers.length === 0) {
+    const description = resolveDescription(response);
+
+    if (content.length === 0 && !description && headers.length === 0) {
         return null;
     }
 
     return (
-        <>
-            {response.description ? (
-                <Markdown source={response.description} className="openapi-response-description" />
-            ) : null}
-
+        <div className="openapi-response-body">
             {headers.length > 0 ? (
-                <InteractiveSection
-                    toggeable
-                    defaultOpened={!!context.defaultInteractiveOpened}
-                    toggleCloseIcon={context.icons.chevronDown}
-                    toggleOpenIcon={context.icons.chevronRight}
-                    header="Headers"
-                    className={classNames('openapi-responseheaders')}
-                >
+                <OpenAPIDisclosure context={context} label={'Headers'}>
                     <OpenAPISchemaProperties
                         properties={headers.map(([name, header]) => ({
                             propertyName: name,
-                            schema: noReference(header.schema) ?? {},
+                            schema: header.schema ?? {},
                             required: header.required,
                         }))}
                         context={context}
                     />
-                </InteractiveSection>
+                </OpenAPIDisclosure>
             ) : null}
-            {content.length > 0 ? (
-                <InteractiveSection
-                    header="Body"
-                    className={classNames('openapi-responsebody')}
-                    tabs={content.map(([contentType, mediaType]) => {
-                        return {
-                            key: contentType,
-                            label: contentType,
-                            body: (
-                                <OpenAPIRootSchema
-                                    schema={noReference(mediaType.schema) ?? {}}
-                                    context={context}
-                                />
-                            ),
-                        };
-                    })}
+            <div className="openapi-responsebody">
+                <OpenAPISchemaProperties
+                    id={`response-${context.blockKey}`}
+                    properties={[
+                        {
+                            schema: mediaType.schema ?? {},
+                        },
+                    ]}
+                    context={context}
                 />
-            ) : null}
-        </>
+            </div>
+        </div>
     );
 }

package/src/OpenAPIResponseExample.tsx

@@ -1,9 +1,10 @@
-import * as React from 'react';
-import { InteractiveSection } from './InteractiveSection';
-import { OpenAPIOperationData } from './fetchOpenAPIOperation';
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import { generateSchemaExample } from './generateSchemaExample';
-import { OpenAPIContextProps } from './types';
-import { createStateKey, noReference } from './utils';
+import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
+import { checkIsReference, createStateKey, resolveDescription } from './utils';
+import { stringifyOpenAPI } from './stringifyOpenAPI';
+import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
+import { InteractiveSection } from './InteractiveSection';
 
 /**
  * Display an example of the response content.
@@ -38,50 +39,107 @@ export function OpenAPIResponseExample(props: {
     });
 
     const examples = responses
-        .map((response) => {
-            const responseObject = noReference(response[1]);
-
-            const schema = noReference(
-                (
-                    responseObject.content?.['application/json'] ??
-                    responseObject.content?.[Object.keys(responseObject.content)[0]]
-                )?.schema,
-            );
+        .map(([key, value]) => {
+            const responseObject = value;
+            const mediaTypeObject = (() => {
+                if (!responseObject.content) {
+                    return null;
+                }
+                const key = Object.keys(responseObject.content)[0];
+                return (
+                    responseObject.content['application/json'] ??
+                    (key ? responseObject.content[key] : null)
+                );
+            })();
 
-            if (!schema) {
-                return null;
+            if (!mediaTypeObject) {
+                return {
+                    key: key,
+                    label: key,
+                    description: resolveDescription(responseObject),
+                    body: <OpenAPIEmptyResponseExample />,
+                };
             }
 
-            const example = generateSchemaExample(schema);
-            if (example === undefined) {
-                return null;
-            }
+            const example = handleUnresolvedReference(
+                (() => {
+                    const { examples, example } = mediaTypeObject;
+                    if (examples) {
+                        const key = Object.keys(examples)[0];
+                        if (key) {
+                            // @TODO handle multiple examples
+                            const firstExample = examples[key];
+                            if (firstExample) {
+                                return firstExample;
+                            }
+                        }
+                    }
+
+                    if (example) {
+                        return { value: example };
+                    }
+
+                    const schema = mediaTypeObject.schema;
+                    if (!schema) {
+                        return null;
+                    }
+
+                    return { value: generateSchemaExample(schema) };
+                })(),
+            );
 
             return {
-                key: `${response[0]}`,
-                label: `${response[0]}`,
-                body: (
+                key: key,
+                label: key,
+                description: resolveDescription(responseObject),
+                body: example?.value ? (
                     <context.CodeBlock
                         code={
-                            typeof example === 'string' ? example : JSON.stringify(example, null, 2)
+                            typeof example.value === 'string'
+                                ? example.value
+                                : stringifyOpenAPI(example.value, null, 2)
                         }
                         syntax="json"
                     />
+                ) : (
+                    <OpenAPIEmptyResponseExample />
                 ),
             };
         })
-        .filter((val): val is { key: string; label: string; body: any } => Boolean(val));
+        .filter((val): val is { key: string; label: string; body: any; description: string } =>
+            Boolean(val),
+        );
 
     if (examples.length === 0) {
         return null;
     }
 
     return (
-        <InteractiveSection
-            stateKey={createStateKey('response', context.blockKey)}
-            header="Response"
-            className="openapi-response-example"
-            tabs={examples}
-        />
+        <OpenAPITabs stateKey={createStateKey('response-example')} items={examples}>
+            <InteractiveSection header={<OpenAPITabsList />} className="openapi-response-example">
+                <OpenAPITabsPanels />
+            </InteractiveSection>
+        </OpenAPITabs>
     );
 }
+
+function OpenAPIEmptyResponseExample() {
+    return (
+        <pre className="openapi-response-example-empty">
+            <p>No body</p>
+        </pre>
+    );
+}
+
+function handleUnresolvedReference(
+    input: OpenAPIV3.ExampleObject | null,
+): OpenAPIV3.ExampleObject | null {
+    const isReference = checkIsReference(input?.value);
+
+    if (isReference) {
+        // If we find a reference that wasn't resolved or needed to be resolved externally, render out the URL
+        return { value: input.value.$ref };
+    }
+
+    return input;
+}

package/src/OpenAPIResponses.tsx

@@ -1,32 +1,63 @@
-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 { 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;
 
     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} />,
-                };
-            })}
-        />
+        <InteractiveSection 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 = response.description;
+
+                        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', () => {