@gitbook/react-openapi 1.0.2 → 1.0.4

package/src/code-samples.ts

@@ -1,3 +1,13 @@
+import {
+    isCSV,
+    isFormData,
+    isFormUrlEncoded,
+    isGraphQL,
+    isPDF,
+    isPlainObject,
+    isText,
+    isXML,
+} from './contentTypeChecks';
 import { stringifyOpenAPI } from './stringifyOpenAPI';
 
 export interface CodeSampleInput {
@@ -30,14 +40,27 @@ export const codeSampleGenerators: CodeSampleGenerator[] = [
 
             lines.push(`--url '${url}'`);
 
-            if (headers) {
+            if (body) {
+                const bodyContent = BodyGenerators.getCurlBody(body, headers);
+
+                if (bodyContent) {
+                    body = bodyContent.body;
+                    headers = bodyContent.headers;
+                }
+            }
+
+            if (headers && Object.keys(headers).length > 0) {
                 Object.entries(headers).forEach(([key, value]) => {
                     lines.push(`--header '${key}: ${value}'`);
                 });
             }
 
-            if (body && Object.keys(body).length > 0) {
-                lines.push(`--data '${stringifyOpenAPI(body)}'`);
+            if (body) {
+                if (Array.isArray(body)) {
+                    lines.push(...body);
+                } else {
+                    lines.push(body);
+                }
             }
 
             return lines.map((line, index) => (index > 0 ? indent(line, 2) : line)).join(separator);
@@ -50,19 +73,30 @@ export const codeSampleGenerators: CodeSampleGenerator[] = [
         generate: ({ method, url, headers, body }) => {
             let code = '';
 
+            if (body) {
+                const lines = BodyGenerators.getJavaScriptBody(body, headers);
+
+                if (lines) {
+                    // add the generated code to the top
+                    code += lines.code;
+                    body = lines.body;
+                    headers = lines.headers;
+                }
+            }
+
             code += `const response = await fetch('${url}', {
     method: '${method.toUpperCase()}',\n`;
 
-            if (headers) {
+            if (headers && Object.keys(headers).length > 0) {
                 code += indent(`headers: ${stringifyOpenAPI(headers, null, 2)},\n`, 4);
             }
 
             if (body) {
-                code += indent(`body: JSON.stringify(${stringifyOpenAPI(body, null, 2)}),\n`, 4);
+                code += indent(`body: ${body}\n`, 4);
             }
 
-            code += `});\n`;
-            code += `const data = await response.json();`;
+            code += '});\n\n';
+            code += 'const data = await response.json();';
 
             return code;
         },
@@ -73,16 +107,35 @@ export const codeSampleGenerators: CodeSampleGenerator[] = [
         syntax: 'python',
         generate: ({ method, url, headers, body }) => {
             let code = 'import requests\n\n';
+
+            if (body) {
+                const lines = BodyGenerators.getPythonBody(body, headers);
+
+                // add the generated code to the top
+                if (lines) {
+                    code += lines.code;
+                    body = lines.body;
+                    headers = lines.headers;
+                }
+            }
+
             code += `response = requests.${method.toLowerCase()}(\n`;
             code += indent(`"${url}",\n`, 4);
-            if (headers) {
+
+            if (headers && Object.keys(headers).length > 0) {
                 code += indent(`headers=${stringifyOpenAPI(headers)},\n`, 4);
             }
+
             if (body) {
-                code += indent(`json=${stringifyOpenAPI(body)}\n`, 4);
+                if (body === 'files') {
+                    code += indent(`files=${body}\n`, 4);
+                } else {
+                    code += indent(`data=${stringifyOpenAPI(body)}\n`, 4);
+                }
             }
-            code += ')\n';
-            code += `data = response.json()`;
+
+            code += ')\n\n';
+            code += 'data = response.json()';
             return code;
         },
     },
@@ -99,6 +152,12 @@ export const codeSampleGenerators: CodeSampleGenerator[] = [
                 // handle unicode chars with a text encoder
                 const encoder = new TextEncoder();
 
+                const bodyString = BodyGenerators.getHTTPBody(body, headers);
+
+                if (bodyString) {
+                    body = bodyString;
+                }
+
                 headers = {
                     ...headers,
                     'Content-Length': encoder.encode(bodyContent).length.toString(),
@@ -110,14 +169,14 @@ export const codeSampleGenerators: CodeSampleGenerator[] = [
             }
 
             const headerString = headers
-                ? Object.entries(headers)
+                ? `${Object.entries(headers)
                       .map(([key, value]) =>
-                          key.toLowerCase() !== 'host' ? `${key}: ${value}` : ``,
+                          key.toLowerCase() !== 'host' ? `${key}: ${value}` : ''
                       )
-                      .join('\n') + '\n'
+                      .join('\n')}\n`
                 : '';
 
-            const bodyString = body ? `\n${stringifyOpenAPI(body, null, 2)}` : '';
+            const bodyString = body ? `\n${body}` : '';
 
             const httpRequest = `${method.toUpperCase()} ${decodeURI(path)} HTTP/1.1
 Host: ${host}
@@ -141,7 +200,7 @@ export function parseHostAndPath(url: string) {
         const urlObj = new URL(url);
         const path = urlObj.pathname || '/';
         return { host: urlObj.host, path };
-    } catch (e) {
+    } catch (_e) {
         // If the URL was invalid do our best to parse the URL.
         // Check for the protocol part and pull it off to grab the host
         const splitted = url.split('//');
@@ -152,8 +211,170 @@ export function parseHostAndPath(url: string) {
         // pull off the host (mutates)
         const host = parts.shift();
         // add a leading slash and join the paths again
-        const path = '/' + parts.join('/');
+        const path = `/${parts.join('/')}`;
 
         return { host, path };
     }
 }
+
+// Body Generators
+const BodyGenerators = {
+    getCurlBody(body: any, headers?: Record<string, string>) {
+        if (!body || !headers) return undefined;
+
+        // Copy headers to avoid mutating the original object
+        const headersCopy = { ...headers };
+        const contentType: string = headersCopy['Content-Type'] || '';
+
+        if (isFormData(contentType)) {
+            body = isPlainObject(body)
+                ? Object.entries(body).map(([key, value]) => `--form '${key}=${String(value)}'`)
+                : `--form 'file=@${body}'`;
+        } else if (isFormUrlEncoded(contentType)) {
+            body = isPlainObject(body)
+                ? `--data '${Object.entries(body)
+                      .map(([key, value]) => `${key}=${String(value)}`)
+                      .join('&')}'`
+                : String(body);
+        } else if (isText(contentType)) {
+            body = `--data '${String(body).replace(/"/g, '')}'`;
+        } else if (isXML(contentType) || isCSV(contentType)) {
+            // We use --data-binary to avoid cURL converting newlines to \r\n
+            body = `--data-binary $'${stringifyOpenAPI(body).replace(/"/g, '')}'`;
+        } else if (isGraphQL(contentType)) {
+            body = `--data '${stringifyOpenAPI(body)}'`;
+            // Set Content-Type to application/json for GraphQL, recommended by GraphQL spec
+            headersCopy['Content-Type'] = 'application/json';
+        } else if (isPDF(contentType)) {
+            // We use --data-binary to avoid cURL converting newlines to \r\n
+            body = `--data-binary '@${String(body)}'`;
+        } else {
+            body = `--data '${stringifyOpenAPI(body, null, 2)}'`;
+        }
+
+        return {
+            body,
+            headers: headersCopy,
+        };
+    },
+    getJavaScriptBody: (body: any, headers?: Record<string, string>) => {
+        if (!body || !headers) return;
+
+        let code = '';
+
+        // Copy headers to avoid mutating the original object
+        const headersCopy = { ...headers };
+        const contentType: string = headersCopy['Content-Type'] || '';
+
+        // Use FormData for file uploads
+        if (isFormData(contentType)) {
+            code += 'const formData = new FormData();\n\n';
+            if (isPlainObject(body)) {
+                Object.entries(body).forEach(([key, value]) => {
+                    code += `formData.append("${key}", "${String(value)}");\n`;
+                });
+            } else if (typeof body === 'string') {
+                code += `formData.append("file", "${body}");\n`;
+            }
+            code += '\n';
+            body = 'formData';
+        } else if (isFormUrlEncoded(contentType)) {
+            // Use URLSearchParams for form-urlencoded data
+            code += 'const params = new URLSearchParams();\n\n';
+            if (isPlainObject(body)) {
+                Object.entries(body).forEach(([key, value]) => {
+                    code += `params.append("${key}", "${String(value)}");\n`;
+                });
+            }
+            code += '\n';
+            body = 'params.toString()';
+        } else if (isGraphQL(contentType)) {
+            if (isPlainObject(body)) {
+                Object.entries(body).forEach(([key, value]) => {
+                    code += `const ${key} = \`\n${indent(String(value), 4)}\`;\n\n`;
+                });
+                body = `JSON.stringify({ ${Object.keys(body).join(', ')} })`;
+                // Set Content-Type to application/json for GraphQL, recommended by GraphQL spec
+                headersCopy['Content-Type'] = 'application/json';
+            } else {
+                code += `const query = \`\n${indent(String(body), 4)}\`;\n\n`;
+                body = 'JSON.stringify(query)';
+            }
+        } else if (isCSV(contentType)) {
+            code += 'const csv = `\n';
+            code += indent(String(body), 4);
+            code += '`;\n\n';
+            body = 'csv';
+        } else if (isPDF(contentType)) {
+            // Use FormData to upload PDF files
+            code += 'const formData = new FormData();\n\n';
+            code += `formData.append("file", "${body}");\n\n`;
+            body = 'formData';
+        } else if (isXML(contentType)) {
+            code += 'const xml = `\n';
+            code += indent(String(body), 4);
+            code += '`;\n\n';
+            body = 'xml';
+        } else if (isText(contentType)) {
+            body = stringifyOpenAPI(body, null, 2);
+        } else {
+            body = `JSON.stringify(${stringifyOpenAPI(body, null, 2)})`;
+        }
+
+        return { body, code, headers: headersCopy };
+    },
+    getPythonBody: (body: any, headers?: Record<string, string>) => {
+        if (!body || !headers) return;
+        let code = '';
+        const contentType: string = headers['Content-Type'] || '';
+
+        if (isFormData(contentType)) {
+            code += 'files = {\n';
+            if (isPlainObject(body)) {
+                Object.entries(body).forEach(([key, value]) => {
+                    code += `${indent(`"${key}": "${String(value)}",`, 4)}\n`;
+                });
+            }
+            code += '}\n\n';
+            body = 'files';
+        }
+
+        if (isPDF(contentType)) {
+            code += 'files = {\n';
+            code += `${indent(`"file": "${body}",`, 4)}\n`;
+            code += '}\n\n';
+            body = 'files';
+        }
+
+        return { body, code, headers };
+    },
+    getHTTPBody: (body: any, headers?: Record<string, string>) => {
+        if (!body || !headers) return undefined;
+
+        const contentType: string = headers['Content-Type'] || '';
+
+        const typeHandlers = {
+            pdf: () => `${stringifyOpenAPI(body, null, 2)}`,
+            formUrlEncoded: () => {
+                const encoded = isPlainObject(body)
+                    ? Object.entries(body)
+                          .map(([key, value]) => `${key}=${String(value)}`)
+                          .join('&')
+                    : String(body);
+                return `"${encoded}"`;
+            },
+            text: () => `"${String(body)}"`,
+            xmlOrCsv: () => `"${stringifyOpenAPI(body).replace(/"/g, '')}"`,
+            default: () => `${stringifyOpenAPI(body, null, 2)}`,
+        };
+
+        if (isPDF(contentType)) return typeHandlers.pdf();
+        if (isFormUrlEncoded(contentType)) return typeHandlers.formUrlEncoded();
+        if (isText(contentType)) return typeHandlers.text();
+        if (isXML(contentType) || isCSV(contentType)) {
+            return typeHandlers.xmlOrCsv();
+        }
+
+        return typeHandlers.default();
+    },
+};

package/src/contentTypeChecks.ts

@@ -0,0 +1,35 @@
+export function isJSON(contentType?: string): boolean {
+    return contentType?.toLowerCase().includes('application/json') || false;
+}
+
+export function isXML(contentType?: string): boolean {
+    return contentType?.toLowerCase().includes('application/xml') || false;
+}
+
+export function isGraphQL(contentType?: string): boolean {
+    return contentType?.toLowerCase().includes('application/graphql') || false;
+}
+
+export function isCSV(contentType?: string): boolean {
+    return contentType?.toLowerCase().includes('text/csv') || false;
+}
+
+export function isPDF(contentType?: string): boolean {
+    return contentType?.toLowerCase().includes('application/pdf') || false;
+}
+
+export function isText(contentType?: string): boolean {
+    return contentType?.toLowerCase().includes('text/plain') || false;
+}
+
+export function isFormUrlEncoded(contentType?: string): boolean {
+    return contentType?.toLowerCase().includes('application/x-www-form-urlencoded') || false;
+}
+
+export function isFormData(contentType?: string): boolean {
+    return !!contentType && contentType.toLowerCase().includes('multipart/form-data');
+}
+
+export function isPlainObject(value: unknown): boolean {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/generateSchemaExample.ts

@@ -14,25 +14,29 @@ type GenerateSchemaExampleOptions = Pick<
  */
 export function generateSchemaExample(
     schema: OpenAPIV3.SchemaObject,
-    options?: GenerateSchemaExampleOptions,
+    options?: GenerateSchemaExampleOptions
 ): JSONValue | undefined {
-    return getExampleFromSchema(schema, {
-        emptyString: 'text',
-        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',
+    return getExampleFromSchema(
+        schema,
+        {
+            emptyString: 'text',
+            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',
+            },
+            ...options,
         },
-        ...options,
-    });
+        3 // Max depth for circular references
+    );
 }
 
 /**
@@ -40,7 +44,7 @@ export function generateSchemaExample(
  */
 export function generateMediaTypeExample(
     mediaType: OpenAPIV3.MediaTypeObject,
-    options?: GenerateSchemaExampleOptions,
+    options?: GenerateSchemaExampleOptions
 ): JSONValue | undefined {
     if (mediaType.example) {
         return mediaType.example;

package/src/json2xml.test.ts

@@ -19,7 +19,7 @@ describe('getUrlFromServerState', () => {
         });
 
         expect(xml).toBe(
-            '<?xml version="1.0"?>\n<urls>\n\t<url>https://example.com</url>\n\t<url>https://example.com</url>\n</urls>\n',
+            '<?xml version="1.0"?>\n<urls>\n\t<url>https://example.com</url>\n\t<url>https://example.com</url>\n</urls>\n'
         );
     });
 

package/src/resolveOpenAPIOperation.test.ts

@@ -1,7 +1,7 @@
-import { it, expect, describe } from 'bun:test';
+import { describe, expect, it } from 'bun:test';
 
-import { resolveOpenAPIOperation } from './resolveOpenAPIOperation';
 import { parseOpenAPI, traverse } from '@gitbook/openapi-parser';
+import { resolveOpenAPIOperation } from './resolveOpenAPIOperation';
 
 async function fetchFilesystem(url: string) {
     const response = await fetch(url);
@@ -19,7 +19,7 @@ async function fetchFilesystem(url: string) {
 describe('#resolveOpenAPIOperation', () => {
     it('should resolve refs', async () => {
         const filesystem = await fetchFilesystem(
-            'https://petstore3.swagger.io/api/v3/openapi.json',
+            'https://petstore3.swagger.io/api/v3/openapi.json'
         );
         const resolved = await resolveOpenAPIOperation(filesystem, { method: 'put', path: '/pet' });
 
@@ -49,7 +49,7 @@ describe('#resolveOpenAPIOperation', () => {
 
     it('should support yaml', async () => {
         const filesystem = await fetchFilesystem(
-            'https://petstore3.swagger.io/api/v3/openapi.yaml',
+            'https://petstore3.swagger.io/api/v3/openapi.yaml'
         );
         const resolved = await resolveOpenAPIOperation(filesystem, { method: 'put', path: '/pet' });
 
@@ -98,7 +98,7 @@ describe('#resolveOpenAPIOperation', () => {
 
     it('should resolve to null if the method is not supported', async () => {
         const filesystem = await fetchFilesystem(
-            'https://petstore3.swagger.io/api/v3/openapi.json',
+            'https://petstore3.swagger.io/api/v3/openapi.json'
         );
         const resolved = await resolveOpenAPIOperation(filesystem, {
             method: 'dontexist',
@@ -144,7 +144,7 @@ describe('#resolveOpenAPIOperation', () => {
 
     it('should resolve a ref with whitespace', async () => {
         const filesystem = await fetchFilesystem(
-            ' https://petstore3.swagger.io/api/v3/openapi.json',
+            ' https://petstore3.swagger.io/api/v3/openapi.json'
         );
         const resolved = await resolveOpenAPIOperation(filesystem, {
             method: 'put',

package/src/resolveOpenAPIOperation.ts

@@ -1,13 +1,13 @@
-import { toJSON, fromJSON } from 'flatted';
+import { fromJSON, toJSON } from 'flatted';
 
 import {
-    type OpenAPIV3xDocument,
     type Filesystem,
     type OpenAPIV3,
     type OpenAPIV3_1,
+    type OpenAPIV3xDocument,
     dereference,
 } from '@gitbook/openapi-parser';
-import { OpenAPIOperationData } from './types';
+import type { OpenAPIOperationData } from './types';
 import { checkIsReference } from './utils';
 
 export { toJSON, fromJSON };
@@ -20,7 +20,7 @@ export async function resolveOpenAPIOperation(
     operationDescriptor: {
         path: string;
         method: string;
-    },
+    }
 ): Promise<OpenAPIOperationData | null> {
     const { path, method } = operationDescriptor;
     const schema = await memoDereferenceFilesystem(filesystem);
@@ -102,7 +102,7 @@ async function dereferenceFilesystem(filesystem: Filesystem): Promise<OpenAPIV3x
  */
 function getPathObject(
     schema: OpenAPIV3.Document | OpenAPIV3_1.Document,
-    path: string,
+    path: string
 ): OpenAPIV3.PathItemObject | OpenAPIV3_1.PathItemObject | null {
     if (schema.paths?.[path]) {
         return schema.paths[path];
@@ -115,7 +115,7 @@ function getPathObject(
  */
 function getPathObjectParameter(
     schema: OpenAPIV3.Document | OpenAPIV3_1.Document,
-    path: string,
+    path: string
 ):
     | (OpenAPIV3.ReferenceObject | OpenAPIV3.ParameterObject)[]
     | (OpenAPIV3.ParameterObject | OpenAPIV3_1.ReferenceObject)[]
@@ -133,7 +133,7 @@ function getPathObjectParameter(
 function getOperationByPathAndMethod(
     schema: OpenAPIV3.Document | OpenAPIV3_1.Document,
     path: string,
-    method: string,
+    method: string
 ): OpenAPIV3.OperationObject | null {
     // Types are buffy for OpenAPIV3_1.OperationObject, so we use v3
     const pathObject = getPathObject(schema, path);

package/src/stringifyOpenAPI.ts

@@ -1,6 +1,17 @@
 /**
  * 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);
+export function stringifyOpenAPI(body: unknown, _?: null, indent?: number): string {
+    return JSON.stringify(
+        body,
+        (key, value) => {
+            // Ignore internal keys
+            if (key.startsWith('x-gitbook-')) {
+                return undefined;
+            }
+
+            return value;
+        },
+        indent
+    );
 }

package/src/types.ts

@@ -5,8 +5,18 @@ import type {
 } from '@gitbook/openapi-parser';
 
 export interface OpenAPIContextProps extends OpenAPIClientContext {
-    CodeBlock: React.ComponentType<{ code: string; syntax: string }>;
+    /**
+     * Render a code block.
+     */
+    renderCodeBlock: (props: { code: string; syntax: string }) => React.ReactNode;
+    /**
+     * Render the heading of the operation.
+     */
     renderHeading: (props: { deprecated: boolean; title: string }) => React.ReactNode;
+    /**
+     * Render the document of the operation.
+     */
+    renderDocument: (props: { document: object }) => React.ReactNode;
 
     /** Spec url for the Scalar Api Client */
     specUrl: string;

package/src/util/server.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'bun:test';
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import { getDefaultServerURL, interpolateServerURL } from './server';
+
+describe('#interpolateServerURL', () => {
+    it('interpolates the server URL with the default values of the variables', () => {
+        const server: OpenAPIV3.ServerObject = {
+            url: 'https://{username}.example.com/{basePath}',
+            variables: {
+                username: { default: 'user' },
+                basePath: { default: 'v1' },
+            },
+        };
+        const result = interpolateServerURL(server);
+        expect(result).toBe('https://user.example.com/v1');
+    });
+
+    it('returns the URL with placeholders if no variables are provided', () => {
+        const server: OpenAPIV3.ServerObject = {
+            url: 'https://{username}.example.com/{basePath}',
+        };
+        const result = interpolateServerURL(server);
+        expect(result).toBe('https://{username}.example.com/{basePath}');
+    });
+
+    it('returns the URL with mixed placeholders and default values', () => {
+        const server: OpenAPIV3.ServerObject = {
+            url: 'https://{username}.example.com/{basePath}',
+            variables: {
+                basePath: { default: 'v1' },
+            },
+        };
+        const result = interpolateServerURL(server);
+        expect(result).toBe('https://{username}.example.com/v1');
+    });
+});
+
+describe('#getDefaultServerURL', () => {
+    it('returns the default server URL', () => {
+        const servers: OpenAPIV3.ServerObject[] = [
+            {
+                url: 'https://{username}.example.com/{basePath}',
+                variables: {
+                    username: { default: 'user' },
+                    basePath: { default: 'v1' },
+                },
+            },
+        ];
+        const result = getDefaultServerURL(servers);
+        expect(result).toBe('https://user.example.com/v1');
+    });
+
+    it('returns empty string if no servers are provided', () => {
+        const servers: OpenAPIV3.ServerObject[] = [];
+        const result = getDefaultServerURL(servers);
+        expect(result).toBe('');
+    });
+});

package/src/util/server.ts

@@ -0,0 +1,47 @@
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+
+/**
+ * Get the default URL for the server.
+ */
+export function getDefaultServerURL(servers: OpenAPIV3.ServerObject[]): string {
+    const server = servers[0];
+    if (!server) {
+        // Return empty string if no server is found to display nothing
+        return '';
+    }
+
+    return interpolateServerURL(server);
+}
+
+/**
+ * Interpolate the server URL with the default values of the variables.
+ */
+export function interpolateServerURL(server: OpenAPIV3.ServerObject) {
+    const parts = parseServerURL(server?.url ?? '');
+
+    return parts
+        .map((part) => {
+            if (part.kind === 'text') {
+                return part.text;
+            }
+            return server.variables?.[part.name]?.default ?? `{${part.name}}`;
+        })
+        .join('');
+}
+
+function parseServerURL(url: string) {
+    const parts = url.split(/{([^}]+)}/g);
+    const result: Array<{ kind: 'variable'; name: string } | { kind: 'text'; text: string }> = [];
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        if (!part) {
+            continue;
+        }
+        if (i % 2 === 0) {
+            result.push({ kind: 'text', text: part });
+        } else {
+            result.push({ kind: 'variable', name: part });
+        }
+    }
+    return result;
+}