@gitbook/react-openapi 1.1.3 → 1.1.5

package/package.json

@@ -8,7 +8,7 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "1.1.3",
+    "version": "1.1.5",
     "sideEffects": false,
     "dependencies": {
         "@gitbook/openapi-parser": "workspace:*",

package/src/OpenAPICodeSample.tsx

@@ -1,4 +1,6 @@
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
+import { ScalarApiButton } from './ScalarApiButton';
 import { StaticSection } from './StaticSection';
 import { type CodeSampleInput, codeSampleGenerators } from './code-samples';
 import { generateMediaTypeExample, generateSchemaExample } from './generateSchemaExample';
@@ -26,13 +28,17 @@ export function OpenAPICodeSample(props: {
         }
 
         if (param.in === 'header' && param.required) {
-            const example = param.schema ? generateSchemaExample(param.schema) : undefined;
+            const example = param.schema
+                ? generateSchemaExample(param.schema, { mode: 'write' })
+                : undefined;
             if (example !== undefined && param.name) {
                 headersObject[param.name] =
                     typeof example !== 'string' ? stringifyOpenAPI(example) : example;
             }
         } else if (param.in === 'query' && param.required) {
-            const example = param.schema ? generateSchemaExample(param.schema) : undefined;
+            const example = param.schema
+                ? generateSchemaExample(param.schema, { mode: 'write' })
+                : undefined;
             if (example !== undefined && param.name) {
                 searchParams.append(
                     param.name,
@@ -75,6 +81,7 @@ export function OpenAPICodeSample(props: {
             code: generator.generate(input),
             syntax: generator.syntax,
         }),
+        footer: <OpenAPICodeSampleFooter data={data} context={context} />,
     }));
 
     // Use custom samples if defined
@@ -101,6 +108,7 @@ export function OpenAPICodeSample(props: {
                         code: sample.source,
                         syntax: sample.lang,
                     }),
+                    footer: <OpenAPICodeSampleFooter data={data} context={context} />,
                 }));
         }
     });
@@ -124,6 +132,30 @@ export function OpenAPICodeSample(props: {
     );
 }
 
+function OpenAPICodeSampleFooter(props: {
+    data: OpenAPIOperationData;
+    context: OpenAPIContextProps;
+}) {
+    const { data, context } = props;
+    const { method, path } = data;
+    const { specUrl } = context;
+    const hideTryItPanel = data['x-hideTryItPanel'] || data.operation['x-hideTryItPanel'];
+
+    if (hideTryItPanel) {
+        return null;
+    }
+
+    if (!validateHttpMethod(method)) {
+        return null;
+    }
+
+    return (
+        <div className="openapi-codesample-footer">
+            <ScalarApiButton method={method} path={path} specUrl={specUrl} />
+        </div>
+    );
+}
+
 function getSecurityHeaders(securities: OpenAPIOperationData['securities']): {
     [key: string]: string;
 } {
@@ -165,3 +197,7 @@ function getSecurityHeaders(securities: OpenAPIOperationData['securities']): {
         }
     }
 }
+
+function validateHttpMethod(method: string): method is OpenAPIV3.HttpMethods {
+    return ['get', 'post', 'put', 'delete', 'patch', 'head', 'options', 'trace'].includes(method);
+}

package/src/OpenAPICopyButton.tsx

@@ -0,0 +1,54 @@
+'use client';
+
+import { useState } from 'react';
+import { Button, type ButtonProps, Tooltip, TooltipTrigger } from 'react-aria-components';
+
+export function OpenAPICopyButton(
+    props: ButtonProps & {
+        value: string;
+    }
+) {
+    const { value } = props;
+    const { children, onPress, className } = props;
+    const [copied, setCopied] = useState(false);
+    const [isOpen, setIsOpen] = useState(false);
+
+    const handleCopy = () => {
+        if (!value) return;
+        navigator.clipboard.writeText(value).then(() => {
+            setIsOpen(true);
+            setCopied(true);
+
+            setTimeout(() => {
+                setCopied(false);
+            }, 2000);
+        });
+    };
+
+    return (
+        <TooltipTrigger isOpen={isOpen} onOpenChange={setIsOpen} closeDelay={200} delay={200}>
+            <Button
+                type="button"
+                preventFocusOnPress
+                onPress={(e) => {
+                    handleCopy();
+                    onPress?.(e);
+                }}
+                className={`openapi-copy-button ${className}`}
+                {...props}
+            >
+                {children}
+            </Button>
+
+            <Tooltip
+                isOpen={isOpen}
+                onOpenChange={setIsOpen}
+                placement="top"
+                offset={4}
+                className="openapi-tooltip"
+            >
+                {copied ? 'Copied' : 'Copy to clipboard'}{' '}
+            </Tooltip>
+        </TooltipTrigger>
+    );
+}

package/src/OpenAPIOperation.tsx

@@ -35,6 +35,7 @@ export function OpenAPIOperation(props: {
                           title: operation.summary,
                       })
                     : null}
+                <OpenAPIPath data={data} context={context} />
                 {operation.deprecated && <div className="openapi-deprecated">Deprecated</div>}
             </div>
             <div className="openapi-columns">
@@ -49,7 +50,6 @@ export function OpenAPIOperation(props: {
                         </div>
                     ) : null}
                     <OpenAPIOperationDescription operation={operation} context={context} />
-                    <OpenAPIPath data={data} context={context} />
                     <OpenAPISpec data={data} context={clientContext} />
                 </div>
                 <div className="openapi-column-preview">

package/src/OpenAPIPath.tsx

@@ -1,7 +1,6 @@
-import type { OpenAPIV3_1 } from '@gitbook/openapi-parser';
-import type React from 'react';
-import { ScalarApiButton } from './ScalarApiButton';
+import { OpenAPICopyButton } from './OpenAPICopyButton';
 import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
+import { getDefaultServerURL } from './util/server';
 
 /**
  * Display the path of an operation.
@@ -10,63 +9,62 @@ export function OpenAPIPath(props: {
     data: OpenAPIOperationData;
     context: OpenAPIContextProps;
 }) {
-    const { data, context } = props;
-    const { method, path } = data;
-    const { specUrl } = context;
-    const hideTryItPanel = data['x-hideTryItPanel'] || data.operation['x-hideTryItPanel'];
+    const { data } = props;
+    const { method, path, operation } = data;
+
+    const server = getDefaultServerURL(data.servers);
+    const formattedPath = formatPath(path);
 
     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>
-            {!hideTryItPanel && validateHttpMethod(method) && (
-                <ScalarApiButton method={method} path={path} specUrl={specUrl} />
-            )}
+
+            <OpenAPICopyButton
+                value={server + path}
+                className="openapi-path-title"
+                data-deprecated={operation.deprecated}
+            >
+                <span className="openapi-path-server">{server}</span>
+                {formattedPath}
+            </OpenAPICopyButton>
         </div>
     );
 }
 
-function validateHttpMethod(method: string): method is OpenAPIV3_1.HttpMethods {
-    return ['get', 'post', 'put', 'delete', 'patch', 'head', 'options', 'trace'].includes(method);
-}
-
-// Format the path to highlight placeholders
+/**
+ * Format the path by wrapping placeholders in <span> tags.
+ */
 function formatPath(path: string) {
     // Matches placeholders like {id}, {userId}, etc.
-    const regex = /\{(\w+)\}/g;
+    const regex = /\{\s*(\w+)\s*\}|:\w+/g;
 
     const parts: (string | React.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>);
+    //Wrap the variables in <span> tags and maintain either {variable} or :variable
+    path.replace(regex, (match, _, offset) => {
+        if (offset > lastIndex) {
+            parts.push(path.slice(lastIndex, offset));
+        }
+        parts.push(
+            <span key={offset} className="openapi-path-variable">
+                {match}
+            </span>
+        );
         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 === '/') {
-                acc.push(
-                    <span className="openapi-path-separator" key={`sep-${index}`}>
-                        /
-                    </span>
-                );
-            }
+    if (lastIndex < path.length) {
+        parts.push(path.slice(lastIndex));
+    }
 
-            acc.push(part);
-            return acc;
-        },
-        [] as (string | React.JSX.Element)[]
-    );
+    const formattedPath = parts.map((part, index) => {
+        if (typeof part === 'string') {
+            return <span key={index}>{part}</span>;
+        }
+        return part;
+    });
 
-    return <span>{formattedPath}</span>;
+    return formattedPath;
 }

package/src/OpenAPIResponseExample.tsx

@@ -1,4 +1,5 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import { Markdown } from './Markdown';
 import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
 import { StaticSection } from './StaticSection';
 import { generateSchemaExample } from './generateSchemaExample';
@@ -39,44 +40,40 @@ export function OpenAPIResponseExample(props: {
         return Number(a) - Number(b);
     });
 
-    const tabs = responses
-        .map(([key, responseObject]) => {
-            const description = resolveDescription(responseObject);
-
-            if (checkIsReference(responseObject)) {
-                return {
-                    key: key,
-                    label: key,
-                    description,
-                    body: (
-                        <OpenAPIExample
-                            example={getExampleFromReference(responseObject)}
-                            context={context}
-                            syntax="json"
-                        />
-                    ),
-                };
-            }
-
-            if (!responseObject.content || Object.keys(responseObject.content).length === 0) {
-                return {
-                    key: key,
-                    label: key,
-                    description,
-                    body: <OpenAPIEmptyResponseExample />,
-                };
-            }
+    const tabs = responses.map(([key, responseObject]) => {
+        const description = resolveDescription(responseObject);
 
+        if (checkIsReference(responseObject)) {
             return {
                 key: key,
                 label: key,
-                description: resolveDescription(responseObject),
-                body: <OpenAPIResponse context={context} content={responseObject.content} />,
+                body: (
+                    <OpenAPIExample
+                        example={getExampleFromReference(responseObject)}
+                        context={context}
+                        syntax="json"
+                    />
+                ),
+                footer: description ? <Markdown source={description} /> : undefined,
             };
-        })
-        .filter((val): val is { key: string; label: string; body: any; description: string } =>
-            Boolean(val)
-        );
+        }
+
+        if (!responseObject.content || Object.keys(responseObject.content).length === 0) {
+            return {
+                key: key,
+                label: key,
+                body: <OpenAPIEmptyResponseExample />,
+                footer: description ? <Markdown source={description} /> : undefined,
+            };
+        }
+
+        return {
+            key: key,
+            label: key,
+            body: <OpenAPIResponse context={context} content={responseObject.content} />,
+            footer: description ? <Markdown source={description} /> : undefined,
+        };
+    });
 
     if (tabs.length === 0) {
         return null;

package/src/OpenAPISchemaName.tsx

@@ -30,6 +30,7 @@ export function OpenAPISchemaName(props: OpenAPISchemaNameProps) {
                     <span className="openapi-schema-type">{additionalItems}</span>
                 ) : null}
             </span>
+            {schema?.readOnly ? <span className="openapi-schema-readonly">read-only</span> : null}
             {required ? <span className="openapi-schema-required">required</span> : null}
             {schema?.deprecated ? <span className="openapi-deprecated">Deprecated</span> : null}
         </div>

package/src/OpenAPITabs.tsx

@@ -3,14 +3,13 @@
 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 { Markdown } from './Markdown';
 import { getOrCreateTabStoreByKey } from './useSyncedTabsGlobalState';
 
 export type TabItem = {
     key: Key;
     label: string;
     body: React.ReactNode;
-    description?: string;
+    footer?: React.ReactNode;
 };
 
 type OpenAPITabsContextData = {
@@ -140,9 +139,19 @@ export function OpenAPITabsPanels() {
     return (
         <TabPanel key={key} id={key} className="openapi-tabs-panel">
             {selectedTab.body}
-            {selectedTab.description ? (
-                <Markdown source={selectedTab.description} className="openapi-tabs-footer" />
+            {selectedTab.footer ? (
+                <OpenAPITabsPanelFooter>{selectedTab.footer}</OpenAPITabsPanelFooter>
             ) : null}
         </TabPanel>
     );
 }
+
+/**
+ * The OpenAPI Tabs panel footer component.
+ * This component should be used as a child of the OpenAPITabs component.
+ */
+function OpenAPITabsPanelFooter(props: { children: React.ReactNode }) {
+    const { children } = props;
+
+    return <div className="openapi-tabs-footer">{children}</div>;
+}

package/src/ScalarApiButton.tsx

@@ -27,14 +27,14 @@ export function ScalarApiButton(props: {
                     setIsOpen(true);
                 }}
             >
-                <svg xmlns="http://www.w3.org/2000/svg" width="10" height="12" fill="none">
+                Test it
+                <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 12" fill="currentColor">
                     <path
                         stroke="currentColor"
                         strokeWidth="1.5"
                         d="M1 10.05V1.43c0-.2.2-.31.37-.22l7.26 4.08c.17.1.17.33.01.43l-7.26 4.54a.25.25 0 0 1-.38-.21Z"
                     />
                 </svg>
-                Test it
             </button>
 
             {isOpen &&

package/src/schemas/OpenAPISchemas.tsx

@@ -4,13 +4,18 @@ import { OpenAPIRootSchema } from '../OpenAPISchema';
 import { Section, SectionBody } from '../StaticSection';
 import type { OpenAPIClientContext, OpenAPIContextProps, OpenAPISchemasData } from '../types';
 
+type OpenAPISchemasContextProps = Omit<
+    OpenAPIContextProps,
+    'renderCodeBlock' | 'renderHeading' | 'renderDocument'
+>;
+
 /**
  * Display OpenAPI Schemas.
  */
 export function OpenAPISchemas(props: {
     className?: string;
     data: OpenAPISchemasData;
-    context: OpenAPIContextProps;
+    context: OpenAPISchemasContextProps;
 }) {
     const { className, data, context } = props;
     const { schemas } = data;

package/src/schemas/resolveOpenAPISchemas.test.ts

@@ -0,0 +1,174 @@
+import { describe, expect, it } from 'bun:test';
+
+import { parseOpenAPI, traverse } from '@gitbook/openapi-parser';
+import { resolveOpenAPISchemas } from './resolveOpenAPISchemas';
+
+async function fetchFilesystem(url: string) {
+    const response = await fetch(url);
+    const text = await response.text();
+    const filesystem = await parseOpenAPI({ value: text, rootURL: url });
+    const transformedFs = await traverse(filesystem, async (node) => {
+        if ('description' in node && typeof node.description === 'string' && node.description) {
+            node['x-gitbook-description-html'] = node.description;
+        }
+        return node;
+    });
+    return transformedFs;
+}
+
+describe('#resolveOpenAPISchemas', () => {
+    it('should resolve refs', async () => {
+        const filesystem = await fetchFilesystem(
+            'https://petstore3.swagger.io/api/v3/openapi.json'
+        );
+        const resolved = await resolveOpenAPISchemas(filesystem, { schemas: ['Pet', 'Tag'] });
+
+        expect(resolved).toMatchObject({
+            schemas: [
+                {
+                    name: 'Pet',
+                    schema: {
+                        properties: {
+                            tags: {
+                                type: 'array',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        id: {
+                                            format: 'int64',
+                                            type: 'integer',
+                                        },
+                                        name: {
+                                            type: 'string',
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+                {
+                    name: 'Tag',
+                    schema: {
+                        type: 'object',
+                        properties: {
+                            id: {
+                                type: 'integer',
+                                format: 'int64',
+                            },
+                            name: {
+                                type: 'string',
+                            },
+                        },
+                        xml: {
+                            name: 'tag',
+                        },
+                    },
+                },
+            ],
+        });
+    });
+
+    it('should support yaml', async () => {
+        const filesystem = await fetchFilesystem(
+            'https://petstore3.swagger.io/api/v3/openapi.yaml'
+        );
+        const resolved = await resolveOpenAPISchemas(filesystem, { schemas: ['Pet'] });
+
+        expect(resolved).toMatchObject({
+            schemas: [
+                {
+                    name: 'Pet',
+                    schema: {
+                        properties: {
+                            tags: {
+                                type: 'array',
+                                items: {
+                                    properties: {
+                                        id: {
+                                            format: 'int64',
+                                            type: 'integer',
+                                        },
+                                        name: {
+                                            type: 'string',
+                                        },
+                                    },
+                                    type: 'object',
+                                },
+                            },
+                        },
+                    },
+                },
+            ],
+        });
+    });
+
+    it('should resolve circular refs', async () => {
+        const filesystem = await fetchFilesystem('https://api.gitbook.com/openapi.json');
+        const resolved = await resolveOpenAPISchemas(filesystem, {
+            schemas: ['DocumentBlockTabs'],
+        });
+
+        expect(resolved).toMatchObject({
+            schemas: [
+                {
+                    name: 'DocumentBlockTabs',
+                    schema: {
+                        type: 'object',
+                        properties: {
+                            object: {
+                                type: 'string',
+                                enum: ['block'],
+                            },
+                        },
+                    },
+                },
+            ],
+        });
+    });
+
+    it('should resolve to null if the schema does not exist', async () => {
+        const filesystem = await fetchFilesystem(
+            'https://petstore3.swagger.io/api/v3/openapi.json'
+        );
+        const resolved = await resolveOpenAPISchemas(filesystem, {
+            schemas: ['NonExistentSchema'],
+        });
+
+        expect(resolved).toBe(null);
+    });
+
+    it('should parse Swagger 2.0', async () => {
+        const filesystem = await fetchFilesystem('https://petstore.swagger.io/v2/swagger.json');
+        const resolved = await resolveOpenAPISchemas(filesystem, {
+            schemas: ['Pet'],
+        });
+
+        expect(resolved).toMatchObject({
+            schemas: [
+                {
+                    name: 'Pet',
+                    schema: {
+                        properties: {
+                            tags: {
+                                type: 'array',
+                                items: {
+                                    properties: {
+                                        id: {
+                                            format: 'int64',
+                                            type: 'integer',
+                                        },
+                                        name: {
+                                            type: 'string',
+                                        },
+                                    },
+                                    type: 'object',
+                                },
+                            },
+                        },
+                    },
+                },
+            ],
+        });
+    });
+});

package/src/schemas/resolveOpenAPISchemas.ts

@@ -15,21 +15,43 @@ import type { OpenAPISchema, OpenAPISchemasData } from '../types';
  * Schemas are extracted from the OpenAPI components.schemas
  */
 export async function resolveOpenAPISchemas(
-    filesystem: Filesystem<OpenAPIV3xDocument>
+    filesystem: Filesystem<OpenAPIV3xDocument>,
+    options: {
+        schemas: string[];
+    }
 ): Promise<OpenAPISchemasData | null> {
+    const { schemas: selectedSchemas } = options;
+
     const schema = await dereferenceFilesystem(filesystem);
 
-    const schemas = getOpenAPIComponents(schema);
+    const schemas = filterSelectedOpenAPISchemas(schema, selectedSchemas);
+
+    if (schemas.length === 0) {
+        return null;
+    }
 
     return { schemas };
 }
-
 /**
- * Get OpenAPI components.schemas that are not ignored.
+ * Extract selected schemas from the OpenAPI document.
  */
-function getOpenAPIComponents(schema: OpenAPIV3.Document | OpenAPIV3_1.Document): OpenAPISchema[] {
-    const schemas = schema.components?.schemas ?? {};
-    return Object.entries(schemas)
-        .filter(([, schema]) => !shouldIgnoreEntity(schema))
-        .map(([key, schema]) => ({ name: key, schema }));
+export function filterSelectedOpenAPISchemas(
+    schema: OpenAPIV3.Document | OpenAPIV3_1.Document,
+    selectedSchemas: string[]
+): OpenAPISchema[] {
+    const componentsSchemas = schema.components?.schemas ?? {};
+
+    // Preserve the order of the selected schemas
+    return selectedSchemas
+        .map((name) => {
+            const schema = componentsSchemas[name];
+            if (schema && !shouldIgnoreEntity(schema)) {
+                return {
+                    name,
+                    schema,
+                };
+            }
+            return null;
+        })
+        .filter((schema): schema is OpenAPISchema => !!schema);
 }