@gitbook/react-openapi 0.7.1 → 1.0.1

package/src/generateSchemaExample.ts

@@ -1,5 +1,5 @@
-import { OpenAPIV3 } from 'openapi-types';
-import { noReference } from './utils';
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import { getExampleFromSchema } from '@scalar/oas-utils/spec-getters';
 
 type JSONValue = string | number | boolean | null | JSONValue[] | { [key: string]: JSONValue };
 
@@ -11,154 +11,24 @@ export function generateSchemaExample(
     options: {
         onlyRequired?: boolean;
     } = {},
-    ancestors: Set<OpenAPIV3.SchemaObject> = new Set(),
 ): JSONValue | undefined {
-    const { onlyRequired = false } = options;
-
-    if (ancestors.has(schema)) {
-        return undefined;
-    }
-
-    if (typeof schema.example !== 'undefined') {
-        return schema.example;
-    }
-
-    if (schema.enum && schema.enum.length > 0) {
-        return schema.enum[0];
-    }
-
-    if (schema.type === 'string') {
-        if (schema.default) {
-            return schema.default;
-        }
-
-        if (schema.format === 'date-time') {
-            return new Date().toISOString();
-        }
-
-        if (schema.format === 'date') {
-            return new Date().toISOString().split('T')[0];
-        }
-
-        if (schema.format === 'email') {
-            return 'name@gmail.com';
-        }
-
-        if (schema.format === 'hostname') {
-            return 'example.com';
-        }
-
-        if (schema.format === 'ipv4') {
-            return '0.0.0.0';
-        }
-
-        if (schema.format === 'ipv6') {
-            return '2001:0db8:85a3:0000:0000:8a2e:0370:7334';
-        }
-
-        if (schema.format === 'uri') {
-            return 'https://example.com';
-        }
-
-        if (schema.format === 'uuid') {
-            return '123e4567-e89b-12d3-a456-426614174000';
-        }
-
-        if (schema.format === 'binary') {
-            return 'binary';
-        }
-
-        if (schema.format === 'byte') {
-            return 'Ynl0ZXM=';
-        }
-
-        if (schema.format === 'password') {
-            return 'password';
-        }
-
-        return 'text';
-    }
-
-    if (schema.type === 'number' || schema.type === 'integer') {
-        return schema.default || 0;
-    }
-
-    if (schema.type === 'boolean') {
-        return schema.default || false;
-    }
-
-    if (schema.type === 'array') {
-        if (schema.items) {
-            const exampleValue = generateSchemaExample(
-                noReference(schema.items),
-                options,
-                new Set(ancestors).add(schema),
-            );
-            if (exampleValue !== undefined) {
-                return [exampleValue];
-            }
-            return [];
-        }
-        return [];
-    }
-
-    if (schema.properties) {
-        const example: { [key: string]: JSONValue } = {};
-        const props = onlyRequired ? (schema.required ?? []) : Object.keys(schema.properties);
-
-        for (const key of props) {
-            const property = noReference(schema.properties[key]);
-            if (property && (onlyRequired || !property.deprecated)) {
-                const exampleValue = generateSchemaExample(
-                    noReference(property),
-                    options,
-                    new Set(ancestors).add(schema),
-                );
-
-                if (exampleValue !== undefined) {
-                    example[key] = exampleValue;
-                }
-            }
-        }
-        return example;
-    }
-
-    if (schema.oneOf && schema.oneOf.length > 0) {
-        return generateSchemaExample(
-            noReference(schema.oneOf[0]),
-            options,
-            new Set(ancestors).add(schema),
-        );
-    }
-
-    if (schema.anyOf && schema.anyOf.length > 0) {
-        return generateSchemaExample(
-            noReference(schema.anyOf[0]),
-            options,
-            new Set(ancestors).add(schema),
-        );
-    }
-
-    if (schema.allOf && schema.allOf.length > 0) {
-        return schema.allOf.reduce(
-            (acc, curr) => {
-                const example = generateSchemaExample(
-                    noReference(curr),
-                    options,
-                    new Set(ancestors).add(schema),
-                );
-
-                if (typeof example === 'object' && !Array.isArray(example) && example !== null) {
-                    return { ...acc, ...example };
-                }
-
-                return acc;
-            },
-            {} as { [key: string]: JSONValue },
-        );
-    }
-
-    return undefined;
+    return getExampleFromSchema(schema, {
+        emptyString: 'text',
+        omitEmptyAndOptionalProperties: options.onlyRequired,
+        variables: {
+            'date-time': new Date().toISOString(),
+            date: new Date().toISOString().split('T')[0],
+            email: 'name@gmail.com',
+            hostname: 'example.com',
+            ipv4: '0.0.0.0',
+            ipv6: '2001:0db8:85a3:0000:0000:8a2e:0370:7334',
+            uri: 'https://example.com',
+            uuid: '123e4567-e89b-12d3-a456-426614174000',
+            binary: 'binary',
+            byte: 'Ynl0ZXM=',
+            password: 'password',
+        },
+    });
 }
 
 /**
@@ -175,14 +45,17 @@ export function generateMediaTypeExample(
     }
 
     if (mediaType.examples) {
-        const example = mediaType.examples[Object.keys(mediaType.examples)[0]];
-        if (example) {
-            return noReference(example).value;
+        const key = Object.keys(mediaType.examples)[0];
+        if (key) {
+            const example = mediaType.examples[key];
+            if (example) {
+                return example.value;
+            }
         }
     }
 
     if (mediaType.schema) {
-        return generateSchemaExample(noReference(mediaType.schema), options);
+        return generateSchemaExample(mediaType.schema, options);
     }
 
     return undefined;

package/src/index.ts

@@ -1,3 +1,4 @@
-export * from './fetchOpenAPIOperation';
+export * from './resolveOpenAPIOperation';
 export * from './OpenAPIOperation';
-export type { OpenAPIFetcher } from './types';
+export * from './OpenAPIOperationContext';
+export type { OpenAPIOperationData } from './types';

package/src/resolveOpenAPIOperation.test.ts

@@ -0,0 +1,177 @@
+import { it, expect, describe } from 'bun:test';
+
+import { resolveOpenAPIOperation } from './resolveOpenAPIOperation';
+import { parseOpenAPI, traverse } from '@gitbook/openapi-parser';
+
+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-description-html'] = node.description;
+        }
+        return node;
+    });
+    return transformedFs;
+}
+
+describe('#resolveOpenAPIOperation', () => {
+    it('should resolve refs', async () => {
+        const filesystem = await fetchFilesystem(
+            'https://petstore3.swagger.io/api/v3/openapi.json',
+        );
+        const resolved = await resolveOpenAPIOperation(filesystem, { method: 'put', path: '/pet' });
+
+        expect(resolved).toMatchObject({
+            servers: [
+                {
+                    url: '/api/v3',
+                },
+            ],
+            operation: {
+                tags: ['pet'],
+                summary: 'Update an existing pet',
+                description: 'Update an existing pet by Id',
+                requestBody: {
+                    content: {
+                        'application/json': {
+                            schema: {
+                                type: 'object',
+                                required: ['name', 'photoUrls'],
+                            },
+                        },
+                    },
+                },
+            },
+        });
+    });
+
+    it('should support yaml', async () => {
+        const filesystem = await fetchFilesystem(
+            'https://petstore3.swagger.io/api/v3/openapi.yaml',
+        );
+        const resolved = await resolveOpenAPIOperation(filesystem, { method: 'put', path: '/pet' });
+
+        expect(resolved).toMatchObject({
+            servers: [
+                {
+                    url: '/api/v3',
+                },
+            ],
+            operation: {
+                tags: ['pet'],
+                summary: 'Update an existing pet',
+                description: 'Update an existing pet by Id',
+                requestBody: {
+                    content: {
+                        'application/json': {
+                            schema: {
+                                type: 'object',
+                                required: ['name', 'photoUrls'],
+                            },
+                        },
+                    },
+                },
+            },
+        });
+    });
+
+    it('should resolve circular refs', async () => {
+        const filesystem = await fetchFilesystem('https://api.gitbook.com/openapi.json');
+        const resolved = await resolveOpenAPIOperation(filesystem, {
+            method: 'post',
+            path: '/search/ask',
+        });
+
+        expect(resolved).toMatchObject({
+            servers: [
+                {
+                    url: '{host}/v1',
+                },
+            ],
+            operation: {
+                operationId: 'askQuery',
+            },
+        });
+    });
+
+    it('should resolve to null if the method is not supported', async () => {
+        const filesystem = await fetchFilesystem(
+            'https://petstore3.swagger.io/api/v3/openapi.json',
+        );
+        const resolved = await resolveOpenAPIOperation(filesystem, {
+            method: 'dontexist',
+            path: '/pet',
+        });
+
+        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 resolveOpenAPIOperation(filesystem, {
+            method: 'put',
+            path: '/pet',
+        });
+
+        expect(resolved).toMatchObject({
+            servers: [
+                {
+                    url: 'https://petstore.swagger.io/v2',
+                },
+                {
+                    url: 'http://petstore.swagger.io/v2',
+                },
+            ],
+            operation: {
+                tags: ['pet'],
+                summary: 'Update an existing pet',
+                description: '',
+                requestBody: {
+                    content: {
+                        'application/json': {
+                            schema: {
+                                type: 'object',
+                                required: ['name', 'photoUrls'],
+                            },
+                        },
+                    },
+                },
+            },
+        });
+    });
+
+    it('should resolve a ref with whitespace', async () => {
+        const filesystem = await fetchFilesystem(
+            ' https://petstore3.swagger.io/api/v3/openapi.json',
+        );
+        const resolved = await resolveOpenAPIOperation(filesystem, {
+            method: 'put',
+            path: '/pet',
+        });
+
+        expect(resolved).toMatchObject({
+            servers: [
+                {
+                    url: '/api/v3',
+                },
+            ],
+            operation: {
+                tags: ['pet'],
+                summary: 'Update an existing pet',
+                description: 'Update an existing pet by Id',
+                requestBody: {
+                    content: {
+                        'application/json': {
+                            schema: {
+                                type: 'object',
+                                required: ['name', 'photoUrls'],
+                            },
+                        },
+                    },
+                },
+            },
+        });
+    });
+});

package/src/resolveOpenAPIOperation.ts

@@ -0,0 +1,164 @@
+import { toJSON, fromJSON } from 'flatted';
+
+import {
+    type OpenAPIV3xDocument,
+    type Filesystem,
+    type OpenAPIV3,
+    type OpenAPIV3_1,
+    dereference,
+} from '@gitbook/openapi-parser';
+import { OpenAPIOperationData } from './types';
+import { checkIsReference } from './utils';
+
+export { toJSON, fromJSON };
+
+/**
+ * Resolve an OpenAPI operation in a file and compile it to a more usable format.
+ */
+export async function resolveOpenAPIOperation(
+    filesystem: Filesystem<OpenAPIV3xDocument>,
+    operationDescriptor: {
+        path: string;
+        method: string;
+    },
+): Promise<OpenAPIOperationData | null> {
+    const { path, method } = operationDescriptor;
+    const schema = await memoDereferenceFilesystem(filesystem);
+    let operation = getOperationByPathAndMethod(schema, path, method);
+
+    if (!operation) {
+        return null;
+    }
+
+    // Resolve common parameters
+    const commonParameters = getPathObjectParameter(schema, path);
+    if (commonParameters) {
+        operation = {
+            ...operation,
+            parameters: [...commonParameters, ...(operation.parameters ?? [])],
+        };
+    }
+
+    const servers = 'servers' in schema ? (schema.servers ?? []) : [];
+    const security = flattenSecurities(operation.security ?? schema.security ?? []);
+
+    // Resolve securities
+    const securities: OpenAPIOperationData['securities'] = [];
+    for (const entry of security) {
+        const securityKey = Object.keys(entry)[0];
+        if (securityKey) {
+            const securityScheme = schema.components?.securitySchemes?.[securityKey];
+            if (securityScheme && !checkIsReference(securityScheme)) {
+                securities.push([securityKey, securityScheme]);
+            }
+        }
+    }
+
+    return {
+        servers,
+        operation,
+        method,
+        path,
+        securities,
+        'x-codeSamples':
+            typeof schema['x-codeSamples'] === 'boolean' ? schema['x-codeSamples'] : undefined,
+        'x-hideTryItPanel':
+            typeof schema['x-hideTryItPanel'] === 'boolean'
+                ? schema['x-hideTryItPanel']
+                : undefined,
+    };
+}
+
+const dereferenceCache = new WeakMap<Filesystem, Promise<OpenAPIV3xDocument>>();
+
+/**
+ * Memoized version of `dereferenceSchema`.
+ */
+function memoDereferenceFilesystem(filesystem: Filesystem): Promise<OpenAPIV3xDocument> {
+    if (dereferenceCache.has(filesystem)) {
+        return dereferenceCache.get(filesystem) as Promise<OpenAPIV3xDocument>;
+    }
+
+    const promise = dereferenceFilesystem(filesystem);
+    dereferenceCache.set(filesystem, promise);
+    return promise;
+}
+
+/**
+ * Dereference an OpenAPI schema.
+ */
+async function dereferenceFilesystem(filesystem: Filesystem): Promise<OpenAPIV3xDocument> {
+    const result = await dereference(filesystem);
+
+    if (!result.schema) {
+        throw new Error('Failed to dereference OpenAPI document');
+    }
+
+    return result.schema as OpenAPIV3xDocument;
+}
+
+/**
+ * Get a path object from its path.
+ */
+function getPathObject(
+    schema: OpenAPIV3.Document | OpenAPIV3_1.Document,
+    path: string,
+): OpenAPIV3.PathItemObject | OpenAPIV3_1.PathItemObject | null {
+    if (schema.paths?.[path]) {
+        return schema.paths[path];
+    }
+    return null;
+}
+
+/**
+ * Resolve parameters from a path in an OpenAPI schema.
+ */
+function getPathObjectParameter(
+    schema: OpenAPIV3.Document | OpenAPIV3_1.Document,
+    path: string,
+):
+    | (OpenAPIV3.ReferenceObject | OpenAPIV3.ParameterObject)[]
+    | (OpenAPIV3.ParameterObject | OpenAPIV3_1.ReferenceObject)[]
+    | null {
+    const pathObject = getPathObject(schema, path);
+    if (pathObject?.parameters) {
+        return pathObject.parameters;
+    }
+    return null;
+}
+
+/**
+ * Get an operation by its path and method.
+ */
+function getOperationByPathAndMethod(
+    schema: OpenAPIV3.Document | OpenAPIV3_1.Document,
+    path: string,
+    method: string,
+): OpenAPIV3.OperationObject | null {
+    // Types are buffy for OpenAPIV3_1.OperationObject, so we use v3
+    const pathObject = getPathObject(schema, path);
+    if (!pathObject) {
+        return null;
+    }
+    const normalizedMethod = method.toLowerCase();
+    if (!pathObject[normalizedMethod]) {
+        return null;
+    }
+    return pathObject[normalizedMethod];
+}
+
+/**
+ * Flatten security objects in case they are nested.
+ * @example [{bearerAuth:[], basicAuth:[]}] => [{ bearerAuth: [] }, { basicAuth: [] }]
+ */
+function flattenSecurities(security: OpenAPIV3.SecurityRequirementObject[]) {
+    if (!Array.isArray(security) || security.length === 0) {
+        return [];
+    }
+
+    return security.flatMap((securityObject) => {
+        return Object.entries(securityObject).map(([authType, config]) => ({
+            [authType]: config,
+        }));
+    });
+}

package/src/stringifyOpenAPI.ts

@@ -0,0 +1,6 @@
+/**
+ * Stringify an OpenAPI object. Same API as JSON.stringify.
+ */
+export function stringifyOpenAPI(body: unknown, transformer?: null, indent?: number): string {
+    return JSON.stringify(body, transformer, indent);
+}

package/src/types.ts

@@ -1,4 +1,8 @@
-export type IconComponent = React.ComponentType<{ className?: string }>;
+import type {
+    OpenAPICustomOperationProperties,
+    OpenAPICustomSpecProperties,
+    OpenAPIV3,
+} from '@gitbook/openapi-parser';
 
 export interface OpenAPIContextProps extends OpenAPIClientContext {
     CodeBlock: React.ComponentType<{ code: string; syntax: string }>;
@@ -11,6 +15,7 @@ export interface OpenAPIClientContext {
     icons: {
         chevronDown: React.ReactNode;
         chevronRight: React.ReactNode;
+        plus: React.ReactNode;
     };
 
     /**
@@ -26,14 +31,16 @@ export interface OpenAPIClientContext {
     id?: string;
 }
 
-export interface OpenAPIFetcher {
-    /**
-     * Fetch an OpenAPI file by its URL. It should return a fully parsed OpenAPI v3 document.
-     */
-    fetch: (url: string) => Promise<any>;
+export interface OpenAPIOperationData extends OpenAPICustomSpecProperties {
+    path: string;
+    method: string;
 
-    /**
-     * Parse markdown to the react element to render.
-     */
-    parseMarkdown?: (input: string) => Promise<string>;
+    /** Servers to be used for this operation */
+    servers: OpenAPIV3.ServerObject[];
+
+    /** Spec of the operation */
+    operation: OpenAPIV3.OperationObject<OpenAPICustomOperationProperties>;
+
+    /** Securities that should be used for this operation */
+    securities: [string, OpenAPIV3.SecuritySchemeObject][];
 }

package/src/useSyncedTabsGlobalState.ts

@@ -0,0 +1,23 @@
+'use client';
+
+import { create } from 'zustand';
+
+interface SyncedTabsState<T> {
+    tabs: Map<string, T>;
+    setTabs: (updater: (tabs: Map<string, T>) => Map<string, T>) => void;
+}
+
+const useSyncedTabsStore = create<SyncedTabsState<any>>()((set) => ({
+    tabs: new Map<string, any>(),
+    setTabs: (updater) =>
+        set((state) => ({
+            tabs: updater(new Map(state.tabs)), // Ensure a new Map is created for reactivity
+        })),
+}));
+
+// Selector for better performance - only re-renders when tabs change
+export function useSyncedTabsGlobalState<T>() {
+    const tabs = useSyncedTabsStore((state) => state.tabs as Map<string, T>);
+    const setTabs = useSyncedTabsStore((state) => state.setTabs as SyncedTabsState<T>['setTabs']);
+    return [tabs, setTabs] as const;
+}

package/src/utils.ts

@@ -1,13 +1,20 @@
-import { OpenAPIV3 } from 'openapi-types';
+import type { AnyObject, OpenAPIV3 } from '@gitbook/openapi-parser';
 
-export function noReference<T>(input: T | OpenAPIV3.ReferenceObject): T {
-    if (typeof input === 'object' && !!input && '$ref' in input) {
-        throw new Error('Reference found');
-    }
-
-    return input;
+export function checkIsReference(input: unknown): input is OpenAPIV3.ReferenceObject {
+    return typeof input === 'object' && !!input && '$ref' in input;
 }
 
 export function createStateKey(key: string, scope?: string) {
     return scope ? `${scope}_${key}` : key;
 }
+
+/**
+ * Resolve the description of an object.
+ */
+export function resolveDescription(object: AnyObject) {
+    return 'x-description-html' in object && typeof object['x-description-html'] === 'string'
+        ? object['x-description-html']
+        : typeof object.description === 'string'
+          ? object.description
+          : undefined;
+}