@gitbook/react-openapi 0.2.0

package/src/generateSchemaExample.ts

@@ -0,0 +1,189 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { noReference } from './utils';
+
+type JSONValue = string | number | boolean | null | JSONValue[] | { [key: string]: JSONValue };
+
+/**
+ * Generate a JSON example from a schema
+ */
+export function generateSchemaExample(
+    schema: OpenAPIV3.SchemaObject,
+    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;
+}
+
+/**
+ * Generate an example for a media type.
+ */
+export function generateMediaTypeExample(
+    mediaType: OpenAPIV3.MediaTypeObject,
+    options: {
+        onlyRequired?: boolean;
+    } = {},
+): JSONValue | undefined {
+    if (mediaType.example) {
+        return mediaType.example;
+    }
+
+    if (mediaType.examples) {
+        const example = mediaType.examples[Object.keys(mediaType.examples)[0]];
+        if (example) {
+            return noReference(example).value;
+        }
+    }
+
+    if (mediaType.schema) {
+        return generateSchemaExample(noReference(mediaType.schema), options);
+    }
+
+    return undefined;
+}

package/src/index.ts

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

package/src/resolveOpenAPIPath.test.ts

@@ -0,0 +1,60 @@
+import { it, expect } from 'bun:test';
+
+import { resolveOpenAPIPath } from './resolveOpenAPIPath';
+import { OpenAPIFetcher } from './types';
+
+const createFetcherForSchema = (schema: any): OpenAPIFetcher => {
+    return {
+        fetch: async (url) => {
+            return schema;
+        },
+    };
+};
+
+it('should resolve a simple path through objects', async () => {
+    const resolved = await resolveOpenAPIPath(
+        'https://test.com',
+        ['a', 'b', 'c'],
+        createFetcherForSchema({
+            a: {
+                b: {
+                    c: 'hello',
+                },
+            },
+        }),
+    );
+
+    expect(resolved).toBe('hello');
+});
+
+it('should return undefined if the last part of the path does not exists', async () => {
+    const resolved = await resolveOpenAPIPath(
+        'https://test.com',
+        ['a', 'b', 'c'],
+        createFetcherForSchema({
+            a: {
+                b: {
+                    d: 'hello',
+                },
+            },
+        }),
+    );
+
+    expect(resolved).toBe(undefined);
+});
+
+it('should return undefined if a middle part of the path does not exists', async () => {
+    const resolved = await resolveOpenAPIPath(
+        'https://test.com',
+        ['a', 'x', 'c'],
+        createFetcherForSchema({
+            a: {
+                b: {
+                    c: 'hello',
+                },
+            },
+        }),
+    );
+
+    expect(resolved).toBe(undefined);
+});

package/src/resolveOpenAPIPath.ts

@@ -0,0 +1,145 @@
+import { OpenAPIFetcher } from './types';
+
+const SYMBOL_MARKDOWN_PARSED = '__$markdownParsed';
+export const SYMBOL_REF_RESOLVED = '__$refResolved';
+
+/**
+ * Resolve a path in a OpenAPI file.
+ * It resolves any reference needed to resolve the path, ignoring other references outside the path.
+ */
+export async function resolveOpenAPIPath<T>(
+    url: string,
+    dataPath: string[],
+    fetcher: OpenAPIFetcher,
+): Promise<T | undefined> {
+    const data = await fetcher.fetch(url);
+    let value: unknown = data;
+
+    if (!value) {
+        return undefined;
+    }
+
+    const lastKey = dataPath[dataPath.length - 1];
+    dataPath = dataPath.slice(0, -1);
+
+    for (const part of dataPath) {
+        // @ts-ignore
+        if (isRef(value[part])) {
+            await transformAll(url, value, part, fetcher);
+        }
+
+        // @ts-ignore
+        value = value[part];
+
+        // If any part along the path is undefined, return undefined.
+        if (typeof value !== 'object' || value === null) {
+            return undefined;
+        }
+    }
+
+    await transformAll(url, value, lastKey, fetcher);
+
+    // @ts-expect-error
+    return value[lastKey] as T;
+}
+
+/**
+ * Recursively process a part of the OpenAPI spec to resolve all references.
+ */
+async function transformAll(
+    url: string,
+    data: any,
+    key: string | number,
+    fetcher: OpenAPIFetcher,
+): Promise<void> {
+    const value = data[key];
+
+    if (
+        typeof value === 'string' &&
+        key === 'description' &&
+        fetcher.parseMarkdown &&
+        !data[SYMBOL_MARKDOWN_PARSED]
+    ) {
+        // Parse markdown
+        data[SYMBOL_MARKDOWN_PARSED] = true;
+        data[key] = await fetcher.parseMarkdown(value);
+    } else if (
+        typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        value === null
+    ) {
+        // Primitives
+    } else if (typeof value === 'object' && value !== null && SYMBOL_REF_RESOLVED in value) {
+        // Ref was already resolved
+    } else if (isRef(value)) {
+        const ref = value.$ref;
+
+        // Delete the ref to avoid infinite loop with circular references
+        // @ts-ignore
+        delete value.$ref;
+
+        data[key] = await resolveReference(url, ref, fetcher);
+        if (data[key]) {
+            data[key][SYMBOL_REF_RESOLVED] = extractRefName(ref);
+        }
+    } else if (Array.isArray(value)) {
+        // Recursively resolve all references in the array
+        await Promise.all(value.map((item, index) => transformAll(url, value, index, fetcher)));
+    } else if (typeof value === 'object' && value !== null) {
+        // Recursively resolve all references in the object
+        const keys = Object.keys(value);
+        for (const key of keys) {
+            await transformAll(url, value, key, fetcher);
+        }
+    }
+}
+
+async function resolveReference(
+    origin: string,
+    ref: string,
+    fetcher: OpenAPIFetcher,
+): Promise<any> {
+    const parsed = parseReference(origin, ref);
+    return resolveOpenAPIPath(parsed.url, parsed.dataPath, fetcher);
+}
+
+function parseReference(origin: string, ref: string): { url: string; dataPath: string[] } {
+    if (!ref) {
+        return {
+            url: origin,
+            dataPath: [],
+        };
+    }
+
+    if (ref.startsWith('#')) {
+        // Local references
+        const dataPath = ref.split('/').filter(Boolean).slice(1);
+        return {
+            url: origin,
+            dataPath,
+        };
+    }
+
+    // Absolute references
+    const url = new URL(ref, origin);
+    if (url.hash) {
+        const hash = url.hash;
+        url.hash = '';
+        return parseReference(url.toString(), hash);
+    }
+
+    return {
+        url: url.toString(),
+        dataPath: [],
+    };
+}
+
+function extractRefName(ref: string): string {
+    const parts = ref.split('/');
+    return parts[parts.length - 1];
+}
+
+function isRef(ref: any): ref is { $ref: string } {
+    return typeof ref === 'object' && ref !== null && '$ref' in ref && ref.$ref;
+}

package/src/types.ts

@@ -0,0 +1,30 @@
+export type IconComponent = React.ComponentType<{ className?: string }>;
+
+export interface OpenAPIContextProps extends OpenAPIClientContext {
+    CodeBlock: React.ComponentType<{ code: string; syntax: string }>;
+}
+
+export interface OpenAPIClientContext {
+    icons: {
+        chevronDown: React.ReactNode;
+        chevronRight: React.ReactNode;
+    };
+
+    /**
+     * Force all sections to be opened by default.
+     * @default false
+     */
+    defaultInteractiveOpened?: boolean;
+}
+
+export interface OpenAPIFetcher {
+    /**
+     * Fetch an OpenAPI file by its URL. It should return a fully parsed OpenAPI v3 document.
+     */
+    fetch: (url: string) => Promise<any>;
+
+    /**
+     * Parse markdown to the react element to render.
+     */
+    parseMarkdown?: (input: string) => Promise<string>;
+}

package/src/utils.ts

@@ -0,0 +1,9 @@
+import { OpenAPIV3 } from 'openapi-types';
+
+export function noReference<T>(input: T | OpenAPIV3.ReferenceObject): T {
+    if (typeof input === 'object' && !!input && '$ref' in input) {
+        throw new Error('Reference found');
+    }
+
+    return input;
+}