@gitbook/react-openapi 0.7.0 → 1.0.0

package/src/generateSchemaExample.ts

@@ -1,5 +1,6 @@
-import { OpenAPIV3 } from 'openapi-types';
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import { noReference } from './utils';
+import { getExampleFromSchema } from '@scalar/oas-utils/spec-getters';
 
 type JSONValue = string | number | boolean | null | JSONValue[] | { [key: string]: JSONValue };
 
@@ -11,154 +12,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') {
-        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,9 +46,12 @@ 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 noReference(example).value;
+            }
         }
     }
 

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,163 @@
+import { toJSON, fromJSON } from 'flatted';
+
+import {
+    type OpenAPIV3xDocument,
+    type Filesystem,
+    type OpenAPIV3,
+    type OpenAPIV3_1,
+    dereference,
+} from '@gitbook/openapi-parser';
+import { noReference } from './utils';
+import { OpenAPIOperationData } from './types';
+
+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) {
+                securities.push([securityKey, noReference(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.ParameterObject[] | OpenAPIV3_1.ParameterObject[] | null {
+    const pathObject = getPathObject(schema, path);
+    if (pathObject?.parameters) {
+        return pathObject.parameters.map(noReference) as
+            | OpenAPIV3.ParameterObject[]
+            | OpenAPIV3_1.ParameterObject[];
+    }
+    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/utils.ts

@@ -1,13 +1,28 @@
-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) {
+    if (checkIsReference(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;
+}

package/dist/InteractiveSection.js

@@ -1,47 +0,0 @@
-'use client';
-import classNames from 'classnames';
-import React from 'react';
-import { atom, useRecoilState } from 'recoil';
-const syncedTabsAtom = atom({
-    key: 'syncedTabState',
-    default: {},
-});
-/**
- * To optimize rendering, most of the components are server-components,
- * and the interactiveness is mainly handled by a few key components like this one.
- */
-export function InteractiveSection(props) {
-    const { id, className, toggeable = false, defaultOpened = true, tabs = [], defaultTab = tabs[0]?.key, header, children, overlay, toggleOpenIcon = '▶', toggleCloseIcon = '▼', stateKey, } = props;
-    const [syncedTabs, setSyncedTabs] = useRecoilState(syncedTabsAtom);
-    const tabFromState = stateKey && stateKey in syncedTabs
-        ? tabs.find((tab) => tab.key === syncedTabs[stateKey])
-        : undefined;
-    const [opened, setOpened] = React.useState(defaultOpened);
-    const [selectedTabKey, setSelectedTab] = React.useState(tabFromState?.key ?? defaultTab);
-    const selectedTab = tabFromState ?? tabs.find((tab) => tab.key === selectedTabKey) ?? tabs[0];
-    return (React.createElement("div", { id: id, className: classNames('openapi-section', toggeable ? 'openapi-section-toggeable' : null, className, toggeable ? `${className}-${opened ? 'opened' : 'closed'}` : null) },
-        React.createElement("div", { onClick: () => {
-                if (toggeable) {
-                    setOpened(!opened);
-                }
-            }, className: classNames('openapi-section-header', `${className}-header`) },
-            React.createElement("div", { className: classNames('openapi-section-header-content', `${className}-header-content`) }, header),
-            React.createElement("div", { className: classNames('openapi-section-header-controls', `${className}-header-controls`), onClick: (event) => {
-                    event.stopPropagation();
-                } },
-                tabs.length ? (React.createElement("select", { className: classNames('openapi-section-select', 'openapi-select', `${className}-tabs-select`), value: selectedTab.key, onChange: (event) => {
-                        setSelectedTab(event.target.value);
-                        if (stateKey) {
-                            setSyncedTabs((state) => ({
-                                ...state,
-                                [stateKey]: event.target.value,
-                            }));
-                        }
-                        setOpened(true);
-                    } }, tabs.map((tab) => (React.createElement("option", { key: tab.key, value: tab.key }, tab.label))))) : null,
-                (children || selectedTab?.body) && toggeable ? (React.createElement("button", { className: classNames('openapi-section-toggle', `${className}-toggle`), onClick: () => setOpened(!opened) }, opened ? toggleCloseIcon : toggleOpenIcon)) : null)),
-        (!toggeable || opened) && (children || selectedTab?.body) ? (React.createElement("div", { className: classNames('openapi-section-body', `${className}-body`) },
-            children,
-            selectedTab?.body)) : null,
-        overlay));
-}

package/dist/Markdown.js

@@ -1,6 +0,0 @@
-import * as React from 'react';
-import classNames from 'classnames';
-export function Markdown(props) {
-    const { source, className } = props;
-    return (React.createElement("div", { className: classNames('openapi-markdown', className), dangerouslySetInnerHTML: { __html: source } }));
-}