@gitbook/react-openapi 0.2.0

package/src/ScalarApiButton.tsx

@@ -0,0 +1,159 @@
+'use client';
+import {
+    Cookie,
+    getHarRequest,
+    getParametersFromOperation,
+    type TransformedOperation,
+    getRequestFromOperation,
+    Query,
+    Header,
+    RequestBody,
+} from '@scalar/oas-utils';
+import React from 'react';
+
+import { OpenAPIOperationData, fromJSON } from './fetchOpenAPIOperation';
+
+const ApiClientReact = React.lazy(async () => {
+    const mod = await import('@scalar/api-client-react');
+    return { default: mod.ApiClientReact };
+});
+
+const ScalarContext = React.createContext<
+    (fetchOperationData: () => Promise<OpenAPIOperationData>) => void
+>(() => {});
+
+/**
+ * Button which launches the Scalar API Client
+ */
+export function ScalarApiButton(props: {
+    fetchOperationData: () => Promise<OpenAPIOperationData>;
+}) {
+    const { fetchOperationData } = props;
+    const open = React.useContext(ScalarContext);
+
+    return (
+        <div className="scalar scalar-activate">
+            <button
+                className="scalar-activate-button"
+                onClick={() => {
+                    open(fetchOperationData);
+                }}
+            >
+                <svg xmlns="http://www.w3.org/2000/svg" width="10" height="12" fill="none">
+                    <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>
+        </div>
+    );
+}
+
+/**
+ * Wrap the rendering with a context to open the scalar modal.
+ */
+export function ScalarApiClient(props: { children: React.ReactNode }) {
+    const { children } = props;
+
+    const [active, setActive] = React.useState<null | {
+        operationData: OpenAPIOperationData | null;
+    }>(null);
+
+    const proxy = '/~scalar/proxy';
+
+    const open = React.useCallback(
+        async (fetchOperationData: () => Promise<OpenAPIOperationData>) => {
+            setActive({ operationData: null });
+            const operationData = fromJSON(await fetchOperationData());
+            setActive({ operationData });
+        },
+        [],
+    );
+
+    const onClose = React.useCallback(() => {
+        setActive(null);
+    }, []);
+
+    const request = React.useMemo(() => {
+        const operationData = active?.operationData;
+
+        if (!operationData) {
+            return null;
+        }
+
+        const operationId =
+            operationData.operation.operationId ?? operationData.method + operationData.path;
+
+        const operation = {
+            ...operationData,
+            httpVerb: operationData.method,
+            pathParameters: operationData.operation.parameters,
+        } as TransformedOperation;
+
+        const variables = getParametersFromOperation(operation, 'path', false);
+
+        const request = getHarRequest(
+            {
+                url: operationData.path,
+            },
+            getRequestFromOperation(
+                {
+                    ...operation,
+                    information: {
+                        requestBody: operationData.operation.requestBody as RequestBody,
+                    },
+                },
+                { requiredOnly: false },
+            ),
+        );
+
+        return {
+            id: operationId,
+            type: operationData.method,
+            path: operationData.path,
+            variables,
+            cookies: request.cookies.map((cookie: Cookie) => {
+                return { ...cookie, enabled: true };
+            }),
+            query: request.queryString.map((queryString: Query) => {
+                const query: typeof queryString & { required?: boolean } = queryString;
+                return { ...queryString, enabled: query.required ?? true };
+            }),
+            headers: request.headers.map((header: Header) => {
+                return { ...header, enabled: true };
+            }),
+            url: operationData.servers[0]?.url,
+            body: request.postData?.text,
+        };
+    }, [active]);
+
+    return (
+        <ScalarContext.Provider value={open}>
+            {children}
+            {active ? (
+                <div className="scalar">
+                    <div className="scalar-container">
+                        <div className="scalar-app">
+                            <React.Suspense fallback={<ScalarLoading />}>
+                                <ApiClientReact
+                                    close={onClose}
+                                    proxy={proxy}
+                                    isOpen={true}
+                                    request={request}
+                                />
+                            </React.Suspense>
+                        </div>
+                        <div onClick={() => onClose()} className="scalar-app-exit"></div>
+                    </div>
+                </div>
+            ) : null}
+        </ScalarContext.Provider>
+    );
+}
+
+function ScalarLoading() {
+    return <div className="scalar-app-loading">Loading...</div>;
+}

package/src/code-samples.ts

@@ -0,0 +1,76 @@
+export interface CodeSampleInput {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: any;
+}
+
+interface CodeSampleGenerator {
+    id: string;
+    label: string;
+    syntax: string;
+    generate: (operation: CodeSampleInput) => string;
+}
+
+export const codeSampleGenerators: CodeSampleGenerator[] = [
+    {
+        id: 'javascript',
+        label: 'JavaScript',
+        syntax: 'javascript',
+        generate: ({ method, url, headers, body }) => {
+            let code = '';
+
+            code += `const response = await fetch('${url}', {
+    method: '${method.toUpperCase()}',\n`;
+
+            if (headers) {
+                code += indent(`headers: ${JSON.stringify(headers, null, 2)},\n`, 4);
+            }
+
+            if (body) {
+                code += indent(`body: JSON.stringify(${JSON.stringify(body, null, 2)}),\n`, 4);
+            }
+
+            code += `});\n`;
+            code += `const data = await response.json();`;
+
+            return code;
+        },
+    },
+    {
+        id: 'curl',
+        label: 'Curl',
+        syntax: 'bash',
+        generate: ({ method, url, headers, body }) => {
+            const separator = ' \\\n';
+
+            const lines: string[] = ['curl -L'];
+
+            if (method.toUpperCase() !== 'GET') {
+                lines.push(`-X ${method.toUpperCase()}`);
+            }
+
+            if (headers) {
+                Object.entries(headers).forEach(([key, value]) => {
+                    lines.push(`-H '${key}: ${value}'`);
+                });
+            }
+
+            lines.push(`'${url}'`);
+
+            if (body) {
+                lines.push(`-d '${JSON.stringify(body)}'`);
+            }
+
+            return lines.map((line, index) => (index > 0 ? indent(line, 2) : line)).join(separator);
+        },
+    },
+];
+
+function indent(code: string, spaces: number) {
+    const indent = ' '.repeat(spaces);
+    return code
+        .split('\n')
+        .map((line) => (line ? indent + line : ''))
+        .join('\n');
+}

package/src/fetchOpenAPIOperation.test.ts

@@ -0,0 +1,185 @@
+import { it, expect } from 'bun:test';
+
+import { fetchOpenAPIOperation, parseOpenAPIV3 } from './fetchOpenAPIOperation';
+import { OpenAPIFetcher } from './types';
+
+const fetcher: OpenAPIFetcher = {
+    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/src/fetchOpenAPIOperation.ts

@@ -0,0 +1,230 @@
+import { toJSON, fromJSON } from 'flatted';
+import { OpenAPIV3 } from 'openapi-types';
+import YAML from 'yaml';
+import swagger2openapi, { ConvertOutputOptions } from 'swagger2openapi';
+
+import { resolveOpenAPIPath } from './resolveOpenAPIPath';
+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[];
+    '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 async function fetchOpenAPIOperation(
+    input: {
+        url: string;
+        path: string;
+        method: string;
+    },
+    rawFetcher: OpenAPIFetcher,
+): Promise<OpenAPIOperationData | null> {
+    const fetcher = cacheFetcher(rawFetcher);
+
+    let operation = await resolveOpenAPIPath<OpenAPIV3.OperationObject>(
+        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<OpenAPIV3.ParameterObject[]>(
+        input.url,
+        ['paths', input.path, 'parameters'],
+        fetcher,
+    );
+    if (commonParameters) {
+        operation = {
+            ...operation,
+            parameters: [...commonParameters, ...(operation.parameters ?? [])],
+        };
+    }
+
+    // Resolve servers
+    const servers = await resolveOpenAPIPath<OpenAPIV3.ServerObject[]>(
+        input.url,
+        ['servers'],
+        fetcher,
+    );
+
+    // Resolve securities
+    const securities: OpenAPIOperationData['securities'] = [];
+    for (const security of operation.security ?? []) {
+        const securityKey = Object.keys(security)[0];
+
+        const securityScheme = await resolveOpenAPIPath<OpenAPIV3.SecuritySchemeObject>(
+            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: OpenAPIFetcher): OpenAPIFetcher {
+    const cache = new Map<string, Promise<any>>();
+
+    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: string, text: string): Promise<OpenAPIV3.Document> {
+    // Parse the JSON or YAML
+    let data: unknown;
+
+    // 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,
+            })) as ConvertOutputOptions;
+
+            data = result.openapi;
+        } catch (error) {
+            if ((error as Error).name === 'S2OError') {
+                throw new OpenAPIFetchError(
+                    'Failed to convert Swagger 2.0 to OpenAPI 3.0: ' + (error as Error).message,
+                    url,
+                );
+            } else {
+                throw error;
+            }
+        }
+    }
+
+    // @ts-ignore
+    return data;
+}
+
+export class OpenAPIFetchError extends Error {
+    public name = 'OpenAPIFetchError';
+
+    constructor(
+        message: string,
+        public readonly url: string,
+    ) {
+        super(message);
+    }
+}