@gitbook/react-openapi 0.4.0 → 0.6.0

package/dist/fetchOpenAPIOperation.d.ts

@@ -0,0 +1,72 @@
+import { toJSON, fromJSON } from 'flatted';
+import { OpenAPIV3 } from 'openapi-types';
+import { OpenAPIFetcher } from './types';
+export interface OpenAPIOperationData extends OpenAPICustomSpecProperties {
+    path: string;
+    method: 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][];
+}
+/**
+ * Custom properties that can be defined at the entire spec level.
+ */
+export interface OpenAPICustomSpecProperties {
+    /**
+     * If `true`, code samples will not be displayed.
+     * This option can be used to hide code samples for the entire spec.
+     */
+    'x-codeSamples'?: boolean;
+    /**
+     * If `true`, the "Try it" button will not be displayed.
+     * This option can be used to hide code samples for the entire spec.
+     */
+    'x-hideTryItPanel'?: boolean;
+}
+/**
+ * Custom properties that can be defined at the operation level.
+ * These properties are not part of the OpenAPI spec.
+ */
+export interface OpenAPICustomOperationProperties {
+    'x-code-samples'?: OpenAPICustomCodeSample[];
+    'x-codeSamples'?: OpenAPICustomCodeSample[] | false;
+    'x-custom-examples'?: OpenAPICustomCodeSample[];
+    /**
+     * If `true`, the "Try it" button will not be displayed.
+     * https://redocly.com/docs/api-reference-docs/specification-extensions/x-hidetryitpanel/
+     */
+    'x-hideTryItPanel'?: boolean;
+}
+/**
+ * Custom code samples that can be defined at the operation level.
+ * It follows the spec defined by Redocly.
+ * https://redocly.com/docs/api-reference-docs/specification-extensions/x-code-samples/
+ */
+export interface OpenAPICustomCodeSample {
+    lang: string;
+    label: string;
+    source: string;
+}
+export { toJSON, fromJSON };
+/**
+ * Resolve an OpenAPI operation in a file and compile it to a more usable format.
+ */
+export declare function fetchOpenAPIOperation(input: {
+    url: string;
+    path: string;
+    method: string;
+}, rawFetcher: OpenAPIFetcher): Promise<OpenAPIOperationData | null>;
+/**
+ * Parse a raw string into an OpenAPI document.
+ * It will also convert Swagger 2.0 to OpenAPI 3.0.
+ * It can throw an `OpenAPIFetchError` if the document is invalid.
+ */
+export declare function parseOpenAPIV3(url: string, text: string): Promise<OpenAPIV3.Document>;
+export declare class OpenAPIFetchError extends Error {
+    readonly url: string;
+    name: string;
+    constructor(message: string, url: string);
+}

package/dist/fetchOpenAPIOperation.js

@@ -0,0 +1,124 @@
+import { toJSON, fromJSON } from 'flatted';
+import YAML from 'yaml';
+import swagger2openapi from 'swagger2openapi';
+import { resolveOpenAPIPath } from './resolveOpenAPIPath';
+export { toJSON, fromJSON };
+/**
+ * Resolve an OpenAPI operation in a file and compile it to a more usable format.
+ */
+export async function fetchOpenAPIOperation(input, rawFetcher) {
+    const fetcher = cacheFetcher(rawFetcher);
+    let operation = await resolveOpenAPIPath(input.url, ['paths', input.path, input.method], fetcher);
+    if (!operation) {
+        return null;
+    }
+    const specData = await fetcher.fetch(input.url);
+    // Resolve common parameters
+    const commonParameters = await resolveOpenAPIPath(input.url, ['paths', input.path, 'parameters'], fetcher);
+    if (commonParameters) {
+        operation = {
+            ...operation,
+            parameters: [...commonParameters, ...(operation.parameters ?? [])],
+        };
+    }
+    // Resolve servers
+    const servers = await resolveOpenAPIPath(input.url, ['servers'], fetcher);
+    // Resolve securities
+    const securities = [];
+    for (const security of operation.security ?? []) {
+        const securityKey = Object.keys(security)[0];
+        const securityScheme = await resolveOpenAPIPath(input.url, ['components', 'securitySchemes', securityKey], fetcher);
+        if (securityScheme) {
+            securities.push([securityKey, securityScheme]);
+        }
+    }
+    return {
+        servers: servers ?? [],
+        operation,
+        method: input.method,
+        path: input.path,
+        securities,
+        'x-codeSamples': typeof specData['x-codeSamples'] === 'boolean' ? specData['x-codeSamples'] : undefined,
+        'x-hideTryItPanel': typeof specData['x-hideTryItPanel'] === 'boolean'
+            ? specData['x-hideTryItPanel']
+            : undefined,
+    };
+}
+function cacheFetcher(fetcher) {
+    const cache = new Map();
+    return {
+        async fetch(url) {
+            if (cache.has(url)) {
+                return cache.get(url);
+            }
+            const promise = fetcher.fetch(url);
+            cache.set(url, promise);
+            return promise;
+        },
+        parseMarkdown: fetcher.parseMarkdown,
+    };
+}
+/**
+ * Parse a raw string into an OpenAPI document.
+ * It will also convert Swagger 2.0 to OpenAPI 3.0.
+ * It can throw an `OpenAPIFetchError` if the document is invalid.
+ */
+export async function parseOpenAPIV3(url, text) {
+    // Parse the JSON or YAML
+    let data;
+    // Try with JSON
+    try {
+        data = JSON.parse(text);
+    }
+    catch (jsonError) {
+        try {
+            // Try with YAML
+            data = YAML.parse(text);
+        }
+        catch (yamlError) {
+            if (yamlError instanceof Error && yamlError.name.startsWith('YAML')) {
+                throw new OpenAPIFetchError('Failed to parse YAML: ' + yamlError.message, url);
+            }
+            else {
+                throw yamlError;
+            }
+        }
+    }
+    // Convert Swagger 2.0 to OpenAPI 3.0
+    // @ts-ignore
+    if (data && data.swagger) {
+        try {
+            // Convert Swagger 2.0 to OpenAPI 3.0
+            // @ts-ignore
+            const result = (await swagger2openapi.convertObj(data, {
+                resolve: false,
+                resolveInternal: false,
+                laxDefaults: true,
+                laxurls: true,
+                lint: false,
+                prevalidate: false,
+                anchors: true,
+                patch: true,
+            }));
+            data = result.openapi;
+        }
+        catch (error) {
+            if (error.name === 'S2OError') {
+                throw new OpenAPIFetchError('Failed to convert Swagger 2.0 to OpenAPI 3.0: ' + error.message, url);
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    // @ts-ignore
+    return data;
+}
+export class OpenAPIFetchError extends Error {
+    url;
+    name = 'OpenAPIFetchError';
+    constructor(message, url) {
+        super(message);
+        this.url = url;
+    }
+}

package/dist/fetchOpenAPIOperation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/fetchOpenAPIOperation.test.js

@@ -0,0 +1,152 @@
+import { it, expect } from 'bun:test';
+import { fetchOpenAPIOperation, parseOpenAPIV3 } from './fetchOpenAPIOperation';
+const fetcher = {
+    fetch: async (url) => {
+        const response = await fetch(url);
+        return parseOpenAPIV3(url, await response.text());
+    },
+};
+it('should resolve refs', async () => {
+    const resolved = await fetchOpenAPIOperation({
+        url: 'https://petstore3.swagger.io/api/v3/openapi.json',
+        method: 'put',
+        path: '/pet',
+    }, fetcher);
+    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 resolved = await fetchOpenAPIOperation({
+        url: 'https://petstore3.swagger.io/api/v3/openapi.yaml',
+        method: 'put',
+        path: '/pet',
+    }, fetcher);
+    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 resolved = await fetchOpenAPIOperation({
+        url: 'https://api.gitbook.com/openapi.json',
+        method: 'post',
+        path: '/search/ask',
+    }, fetcher);
+    expect(resolved).toMatchObject({
+        servers: [
+            {
+                url: '{host}/v1',
+            },
+        ],
+        operation: {
+            operationId: 'askQuery',
+        },
+    });
+});
+it('should resolve to null if the method is not supported', async () => {
+    const resolved = await fetchOpenAPIOperation({
+        url: 'https://petstore3.swagger.io/api/v3/openapi.json',
+        method: 'dontexist',
+        path: '/pet',
+    }, fetcher);
+    expect(resolved).toBe(null);
+});
+it('should parse Swagger 2.0', async () => {
+    const resolved = await fetchOpenAPIOperation({
+        url: 'https://petstore.swagger.io/v2/swagger.json',
+        method: 'put',
+        path: '/pet',
+    }, fetcher);
+    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 resolved = await fetchOpenAPIOperation({
+        url: ' https://petstore3.swagger.io/api/v3/openapi.json',
+        method: 'put',
+        path: '/pet',
+    }, fetcher);
+    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/dist/generateSchemaExample.d.ts

@@ -0,0 +1,17 @@
+import { OpenAPIV3 } from 'openapi-types';
+type JSONValue = string | number | boolean | null | JSONValue[] | {
+    [key: string]: JSONValue;
+};
+/**
+ * Generate a JSON example from a schema
+ */
+export declare function generateSchemaExample(schema: OpenAPIV3.SchemaObject, options?: {
+    onlyRequired?: boolean;
+}, ancestors?: Set<OpenAPIV3.SchemaObject>): JSONValue | undefined;
+/**
+ * Generate an example for a media type.
+ */
+export declare function generateMediaTypeExample(mediaType: OpenAPIV3.MediaTypeObject, options?: {
+    onlyRequired?: boolean;
+}): JSONValue | undefined;
+export {};

package/dist/generateSchemaExample.js

@@ -0,0 +1,119 @@
+import { noReference } from './utils';
+/**
+ * Generate a JSON example from a schema
+ */
+export function generateSchemaExample(schema, options = {}, ancestors = new Set()) {
+    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 = {};
+        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;
+        }, {});
+    }
+    return undefined;
+}
+/**
+ * Generate an example for a media type.
+ */
+export function generateMediaTypeExample(mediaType, options = {}) {
+    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/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './fetchOpenAPIOperation';
+export * from './OpenAPIOperation';

package/dist/resolveOpenAPIPath.d.ts

@@ -0,0 +1,7 @@
+import { OpenAPIFetcher } from './types';
+export declare 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 declare function resolveOpenAPIPath<T>(url: string, dataPath: string[], fetcher: OpenAPIFetcher): Promise<T | undefined>;

package/dist/resolveOpenAPIPath.js

@@ -0,0 +1,112 @@
+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(url, dataPath, fetcher) {
+    const data = await fetcher.fetch(url);
+    let value = 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];
+}
+/**
+ * Recursively process a part of the OpenAPI spec to resolve all references.
+ */
+async function transformAll(url, data, key, fetcher) {
+    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, ref, fetcher) {
+    const parsed = parseReference(origin, ref);
+    return resolveOpenAPIPath(parsed.url, parsed.dataPath, fetcher);
+}
+function parseReference(origin, ref) {
+    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) {
+    const parts = ref.split('/');
+    return parts[parts.length - 1];
+}
+function isRef(ref) {
+    return typeof ref === 'object' && ref !== null && '$ref' in ref && ref.$ref;
+}

package/dist/resolveOpenAPIPath.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/resolveOpenAPIPath.test.js

@@ -0,0 +1,39 @@
+import { it, expect } from 'bun:test';
+import { resolveOpenAPIPath } from './resolveOpenAPIPath';
+const createFetcherForSchema = (schema) => {
+    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);
+});