@gitbook/react-openapi 1.1.6 → 1.1.7

package/src/OpenAPISchema.tsx

@@ -1,16 +1,22 @@
-import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+'use client';
+// This component does not use any client feature but we don't want to
+// render it server-side because it has recursion.
+
+import type { OpenAPICustomOperationProperties, OpenAPIV3 } from '@gitbook/openapi-parser';
 import { useId } from 'react';
 
 import clsx from 'clsx';
 import { Markdown } from './Markdown';
+import { OpenAPICopyButton } from './OpenAPICopyButton';
 import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 import { OpenAPISchemaName } from './OpenAPISchemaName';
+import { retrocycle } from './decycle';
 import type { OpenAPIClientContext } from './types';
 import { checkIsReference, resolveDescription, resolveFirstExample } from './utils';
 
 type CircularRefsIds = Map<OpenAPIV3.SchemaObject, string>;
 
-interface OpenAPISchemaPropertyEntry {
+export interface OpenAPISchemaPropertyEntry {
     propertyName?: string | undefined;
     required?: boolean | undefined;
     schema: OpenAPIV3.SchemaObject;
@@ -22,15 +28,10 @@ interface OpenAPISchemaPropertyEntry {
 function OpenAPISchemaProperty(props: {
     property: OpenAPISchemaPropertyEntry;
     context: OpenAPIClientContext;
-    circularRefs?: CircularRefsIds;
+    circularRefs: CircularRefsIds;
     className?: string;
 }) {
-    const {
-        property,
-        circularRefs: parentCircularRefs = new Map<OpenAPIV3.SchemaObject, string>(),
-        context,
-        className,
-    } = props;
+    const { circularRefs: parentCircularRefs, context, className, property } = props;
 
     const { schema } = property;
 
@@ -40,37 +41,43 @@ function OpenAPISchemaProperty(props: {
         <div id={id} className={clsx('openapi-schema', className)}>
             <OpenAPISchemaPresentation property={property} />
             {(() => {
-                const parentCircularRef = parentCircularRefs.get(schema);
-
+                const circularRefId = parentCircularRefs.get(schema);
                 // Avoid recursing infinitely, and instead render a link to the parent schema
-                if (parentCircularRef) {
-                    return <OpenAPISchemaCircularRef id={parentCircularRef} schema={schema} />;
+                if (circularRefId) {
+                    return <OpenAPISchemaCircularRef id={circularRefId} schema={schema} />;
                 }
 
-                const circularRefs = parentCircularRefs.set(schema, id);
+                const circularRefs = new Map(parentCircularRefs);
+                circularRefs.set(schema, id);
+
                 const properties = getSchemaProperties(schema);
-                const alternatives = getSchemaAlternatives(schema, new Set(circularRefs.keys()));
-                return (
-                    <>
-                        {alternatives?.map((schema, index) => (
-                            <OpenAPISchemaAlternative
-                                key={index}
-                                schema={schema}
+                if (properties?.length) {
+                    return (
+                        <OpenAPIDisclosure context={context} label={getDisclosureLabel(schema)}>
+                            <OpenAPISchemaProperties
+                                properties={properties}
                                 circularRefs={circularRefs}
                                 context={context}
                             />
-                        ))}
-                        {properties?.length ? (
-                            <OpenAPIDisclosure context={context} label={getDisclosureLabel(schema)}>
-                                <OpenAPISchemaProperties
-                                    properties={properties}
-                                    circularRefs={circularRefs}
-                                    context={context}
-                                />
-                            </OpenAPIDisclosure>
-                        ) : null}
-                    </>
-                );
+                        </OpenAPIDisclosure>
+                    );
+                }
+
+                const ancestors = new Set(circularRefs.keys());
+                const alternatives = getSchemaAlternatives(schema, ancestors);
+
+                if (alternatives) {
+                    return alternatives.map((schema, index) => (
+                        <OpenAPISchemaAlternative
+                            key={index}
+                            schema={schema}
+                            circularRefs={circularRefs}
+                            context={context}
+                        />
+                    ));
+                }
+
+                return null;
             })()}
         </div>
     );
@@ -79,41 +86,77 @@ function OpenAPISchemaProperty(props: {
 /**
  * Render a set of properties of an OpenAPI schema.
  */
-export function OpenAPISchemaProperties(props: {
+function OpenAPISchemaProperties(props: {
     id?: string;
     properties: OpenAPISchemaPropertyEntry[];
     circularRefs?: CircularRefsIds;
     context: OpenAPIClientContext;
 }) {
-    const { id, properties, circularRefs, context } = props;
+    const {
+        id,
+        properties,
+        circularRefs = new Map<OpenAPIV3.SchemaObject, string>(),
+        context,
+    } = props;
 
     return (
         <div id={id} className="openapi-schema-properties">
-            {properties.map((property, index) => (
-                <OpenAPISchemaProperty
-                    key={index}
-                    circularRefs={circularRefs}
-                    property={property}
-                    context={context}
-                />
-            ))}
+            {properties.map((property, index) => {
+                return (
+                    <OpenAPISchemaProperty
+                        key={index}
+                        circularRefs={circularRefs}
+                        property={property}
+                        context={context}
+                    />
+                );
+            })}
         </div>
     );
 }
 
+export function OpenAPISchemaPropertiesFromServer(props: {
+    id?: string;
+    properties: string;
+    context: OpenAPIClientContext;
+}) {
+    return (
+        <OpenAPISchemaProperties
+            id={props.id}
+            properties={JSON.parse(props.properties, retrocycle())}
+            context={props.context}
+        />
+    );
+}
+
 /**
  * Render a root schema (such as the request body or response body).
  */
-export function OpenAPIRootSchema(props: {
+function OpenAPIRootSchema(props: {
     schema: OpenAPIV3.SchemaObject;
     context: OpenAPIClientContext;
+    circularRefs?: CircularRefsIds;
 }) {
-    const { schema, context } = props;
+    const {
+        schema,
+        context,
+        circularRefs: parentCircularRefs = new Map<OpenAPIV3.SchemaObject, string>(),
+    } = props;
 
+    const id = useId();
     const properties = getSchemaProperties(schema);
 
     if (properties?.length) {
-        return <OpenAPISchemaProperties properties={properties} context={context} />;
+        const circularRefs = new Map(parentCircularRefs);
+        circularRefs.set(schema, id);
+
+        return (
+            <OpenAPISchemaProperties
+                properties={properties}
+                circularRefs={circularRefs}
+                context={context}
+            />
+        );
     }
 
     return (
@@ -121,6 +164,19 @@ export function OpenAPIRootSchema(props: {
             className="openapi-schema-root"
             property={{ schema }}
             context={context}
+            circularRefs={parentCircularRefs}
+        />
+    );
+}
+
+export function OpenAPIRootSchemaFromServer(props: {
+    schema: string;
+    context: OpenAPIClientContext;
+}) {
+    return (
+        <OpenAPIRootSchema
+            schema={JSON.parse(props.schema, retrocycle())}
+            context={props.context}
         />
     );
 }
@@ -136,6 +192,7 @@ function OpenAPISchemaAlternative(props: {
     context: OpenAPIClientContext;
 }) {
     const { schema, circularRefs, context } = props;
+
     const description = resolveDescription(schema);
     const properties = getSchemaProperties(schema);
 
@@ -180,20 +237,59 @@ function OpenAPISchemaCircularRef(props: { id: string; schema: OpenAPIV3.SchemaO
 /**
  * Render the enum value for a schema.
  */
-function OpenAPISchemaEnum(props: { enumValues: any[] }) {
-    const { enumValues } = props;
+function OpenAPISchemaEnum(props: {
+    schema: OpenAPIV3.SchemaObject & OpenAPICustomOperationProperties;
+}) {
+    const { schema } = props;
+
+    const enumValues = (() => {
+        // Render x-gitbook-enum first, as it has a different format
+        if (schema['x-gitbook-enum']) {
+            return Object.entries(schema['x-gitbook-enum']).map(([name, { description }]) => {
+                return {
+                    value: name,
+                    description,
+                };
+            });
+        }
+
+        if (schema['x-enumDescriptions']) {
+            return Object.entries(schema['x-enumDescriptions']).map(([value, description]) => {
+                return {
+                    value,
+                    description,
+                };
+            });
+        }
+
+        return schema.enum?.map((value) => {
+            return {
+                value,
+                description: undefined,
+            };
+        });
+    })();
+
+    if (!enumValues?.length) {
+        return null;
+    }
 
     return (
         <div className="openapi-schema-enum">
-            <span>
-                Options:{' '}
-                {enumValues.map((value, index) => (
+            <span>Available options:</span>
+            <div className="openapi-schema-enum-list">
+                {enumValues.map((item, index) => (
                     <span key={index} className="openapi-schema-enum-value">
-                        <code>{`${value}`}</code>
-                        {index < enumValues.length - 1 ? ', ' : ''}
+                        <OpenAPICopyButton
+                            value={item.value}
+                            label={item.description}
+                            withTooltip={!!item.description}
+                        >
+                            <code>{`${item.value}`}</code>
+                        </OpenAPICopyButton>
                     </span>
                 ))}
-            </span>
+            </div>
         </div>
     );
 }
@@ -238,9 +334,7 @@ function OpenAPISchemaPresentation(props: { property: OpenAPISchemaPropertyEntry
                     Pattern: <code>{schema.pattern}</code>
                 </div>
             ) : null}
-            {schema.enum && schema.enum.length > 0 ? (
-                <OpenAPISchemaEnum enumValues={schema.enum} />
-            ) : null}
+            <OpenAPISchemaEnum schema={schema} />
         </div>
     );
 }
@@ -365,7 +459,7 @@ function getSchemaTitle(schema: OpenAPIV3.SchemaObject): string {
     // Otherwise try to infer a nice title
     let type = 'any';
 
-    if (schema.enum) {
+    if (schema.enum || schema['x-enumDescriptions'] || schema['x-gitbook-enum']) {
         type = `${schema.type} · enum`;
         // check array AND schema.items as this is sometimes null despite what the type indicates
     } else if (schema.type === 'array' && !!schema.items) {

package/src/OpenAPISchemaName.tsx

@@ -32,6 +32,9 @@ export function OpenAPISchemaName(props: OpenAPISchemaNameProps) {
                 ) : null}
             </span>
             {schema?.readOnly ? <span className="openapi-schema-readonly">read-only</span> : null}
+            {schema?.writeOnly ? (
+                <span className="openapi-schema-writeonly">write-only</span>
+            ) : null}
             {required ? (
                 <span className="openapi-schema-required">required</span>
             ) : (

package/src/OpenAPISchemaServer.tsx

@@ -0,0 +1,34 @@
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import {
+    OpenAPIRootSchemaFromServer,
+    OpenAPISchemaPropertiesFromServer,
+    type OpenAPISchemaPropertyEntry,
+} from './OpenAPISchema';
+import { decycle } from './decycle';
+import type { OpenAPIClientContext } from './types';
+
+export function OpenAPISchemaProperties(props: {
+    id?: string;
+    properties: OpenAPISchemaPropertyEntry[];
+    context: OpenAPIClientContext;
+}) {
+    return (
+        <OpenAPISchemaPropertiesFromServer
+            id={props.id}
+            properties={JSON.stringify(props.properties, decycle())}
+            context={props.context}
+        />
+    );
+}
+
+export function OpenAPIRootSchema(props: {
+    schema: OpenAPIV3.SchemaObject;
+    context: OpenAPIClientContext;
+}) {
+    return (
+        <OpenAPIRootSchemaFromServer
+            schema={JSON.stringify(props.schema, decycle())}
+            context={props.context}
+        />
+    );
+}

package/src/OpenAPISpec.tsx

@@ -2,18 +2,12 @@ import type { OpenAPI } from '@gitbook/openapi-parser';
 
 import { OpenAPIRequestBody } from './OpenAPIRequestBody';
 import { OpenAPIResponses } from './OpenAPIResponses';
-import { OpenAPISchemaProperties } from './OpenAPISchema';
+import { OpenAPISchemaProperties } from './OpenAPISchemaServer';
 import { OpenAPISecurities } from './OpenAPISecurities';
 import { StaticSection } from './StaticSection';
 import type { OpenAPIClientContext, OpenAPIOperationData } from './types';
 import { parameterToProperty } from './utils';
 
-/**
- * Client component to render the spec for the request and response.
- *
- * We use a client component as rendering recursive JSON schema in the server is expensive
- * (the entire schema is rendered at once, while the client component only renders the visible part)
- */
 export function OpenAPISpec(props: { data: OpenAPIOperationData; context: OpenAPIClientContext }) {
     const { data, context } = props;
 
@@ -25,13 +19,13 @@ export function OpenAPISpec(props: { data: OpenAPIOperationData; context: OpenAP
     return (
         <>
             {securities.length > 0 ? (
-                <OpenAPISecurities securities={securities} context={context} />
+                <OpenAPISecurities key="securities" securities={securities} context={context} />
             ) : null}
 
             {parameterGroups.map((group) => {
                 return (
                     <StaticSection
-                        key={group.key}
+                        key={`parameter-${group.key}`}
                         className="openapi-parameters"
                         header={group.label}
                     >
@@ -44,10 +38,18 @@ export function OpenAPISpec(props: { data: OpenAPIOperationData; context: OpenAP
             })}
 
             {operation.requestBody ? (
-                <OpenAPIRequestBody requestBody={operation.requestBody} context={context} />
+                <OpenAPIRequestBody
+                    key="body"
+                    requestBody={operation.requestBody}
+                    context={context}
+                />
             ) : null}
             {operation.responses ? (
-                <OpenAPIResponses responses={operation.responses} context={context} />
+                <OpenAPIResponses
+                    key="responses"
+                    responses={operation.responses}
+                    context={context}
+                />
             ) : null}
         </>
     );

package/src/OpenAPITabs.tsx

@@ -137,21 +137,11 @@ export function OpenAPITabsPanels() {
     const key = selectedTab.key.toString();
 
     return (
-        <TabPanel key={key} id={key} className="openapi-tabs-panel">
-            {selectedTab.body}
+        <TabPanel id={key} className="openapi-tabs-panel">
+            <div className="openapi-tabs-body">{selectedTab.body}</div>
             {selectedTab.footer ? (
-                <OpenAPITabsPanelFooter>{selectedTab.footer}</OpenAPITabsPanelFooter>
+                <div className="openapi-tabs-footer">{selectedTab.footer}</div>
             ) : null}
         </TabPanel>
     );
 }
-
-/**
- * The OpenAPI Tabs panel footer component.
- * This component should be used as a child of the OpenAPITabs component.
- */
-function OpenAPITabsPanelFooter(props: { children: React.ReactNode }) {
-    const { children } = props;
-
-    return <div className="openapi-tabs-footer">{children}</div>;
-}

package/src/code-samples.test.ts

@@ -110,6 +110,23 @@ describe('curL code sample generator', () => {
         );
     });
 
+    it('should convert json to xml body properly', () => {
+        const input: CodeSampleInput = {
+            method: 'GET',
+            url: 'https://example.com/path',
+            headers: {
+                'Content-Type': 'application/xml',
+            },
+            body: '{ "key": "value" }',
+        };
+
+        const output = generator?.generate(input);
+
+        expect(output).toBe(
+            "curl -L \\\n  --url 'https://example.com/path' \\\n  --header 'Content-Type: application/xml' \\\n  --data-binary $'<?xml version=1.0?>\n  <key>value</key>\n  '"
+        );
+    });
+
     it('should format application/graphql body properly', () => {
         const input: CodeSampleInput = {
             method: 'GET',
@@ -258,6 +275,23 @@ describe('javascript code sample generator', () => {
         );
     });
 
+    it('should convert json to xml body properly', () => {
+        const input: CodeSampleInput = {
+            method: 'GET',
+            url: 'https://example.com/path',
+            headers: {
+                'Content-Type': 'application/xml',
+            },
+            body: '{ "key": "value" }',
+        };
+
+        const output = generator?.generate(input);
+
+        expect(output).toBe(
+            'const xml = `\n    <?xml version=1.0?>\n    <key>value</key>\n`;\n\nconst response = await fetch(\'https://example.com/path\', {\n    method: \'GET\',\n    headers: {\n      "Content-Type": "application/xml"\n    },\n    body: xml\n});\n\nconst data = await response.json();'
+        );
+    });
+
     it('should format application/graphql body properly', () => {
         const input: CodeSampleInput = {
             method: 'GET',
@@ -406,6 +440,23 @@ describe('python code sample generator', () => {
         );
     });
 
+    it('should convert json to xml body properly', () => {
+        const input: CodeSampleInput = {
+            method: 'GET',
+            url: 'https://example.com/path',
+            headers: {
+                'Content-Type': 'application/xml',
+            },
+            body: '{ "key": "value" }',
+        };
+
+        const output = generator?.generate(input);
+
+        expect(output).toBe(
+            'import requests\n\nresponse = requests.get(\n    "https://example.com/path",\n    headers={"Content-Type":"application/xml"},\n    data="<?xml version=1.0?>\\n<key>value</key>\\n"\n)\n\ndata = response.json()'
+        );
+    });
+
     it('should format application/graphql body properly', () => {
         const input: CodeSampleInput = {
             method: 'GET',
@@ -514,7 +565,7 @@ describe('http code sample generator', () => {
         const output = generator?.generate(input);
 
         expect(output).toBe(
-            'GET /path HTTP/1.1\nHost: example.com\nContent-Type: application/x-www-form-urlencoded\nContent-Length: 15\nAccept: */*\n\n"key=value"'
+            'GET /path HTTP/1.1\nHost: example.com\nContent-Type: application/x-www-form-urlencoded\nContent-Length: 15\nAccept: */*\n\n"key=\'value\'"'
         );
     });
 
@@ -554,6 +605,23 @@ describe('http code sample generator', () => {
         );
     });
 
+    it('should convert json to xml body properly', () => {
+        const input: CodeSampleInput = {
+            method: 'GET',
+            url: 'https://example.com/path',
+            headers: {
+                'Content-Type': 'application/xml',
+            },
+            body: '{ "key": "value" }',
+        };
+
+        const output = generator?.generate(input);
+
+        expect(output).toBe(
+            'GET /path HTTP/1.1\nHost: example.com\nContent-Type: application/xml\nContent-Length: 24\nAccept: */*\n\n"<?xml version=1.0?>\n<key>value</key>\n"'
+        );
+    });
+
     it('should format application/graphql body properly', () => {
         const input: CodeSampleInput = {
             method: 'GET',

package/src/code-samples.ts

@@ -8,6 +8,7 @@ import {
     isText,
     isXML,
 } from './contentTypeChecks';
+import { json2xml } from './json2xml';
 import { stringifyOpenAPI } from './stringifyOpenAPI';
 
 export interface CodeSampleInput {
@@ -238,7 +239,10 @@ const BodyGenerators = {
                 : String(body);
         } else if (isText(contentType)) {
             body = `--data '${String(body).replace(/"/g, '')}'`;
-        } else if (isXML(contentType) || isCSV(contentType)) {
+        } else if (isXML(contentType)) {
+            // Convert to XML and ensure proper formatting
+            body = `--data-binary $'${convertBodyToXML(body)}'`;
+        } else if (isCSV(contentType)) {
             // We use --data-binary to avoid cURL converting newlines to \r\n
             body = `--data-binary $'${stringifyOpenAPI(body).replace(/"/g, '').replace(/\\n/g, '\n')}'`;
         } else if (isGraphQL(contentType)) {
@@ -312,7 +316,9 @@ const BodyGenerators = {
             body = 'formData';
         } else if (isXML(contentType)) {
             code += 'const xml = `\n';
-            code += indent(String(body), 4);
+
+            // Convert JSON to XML if needed
+            code += indent(convertBodyToXML(body), 4);
             code += '`;\n\n';
             body = 'xml';
         } else if (isText(contentType)) {
@@ -346,6 +352,11 @@ const BodyGenerators = {
             body = 'files';
         }
 
+        if (isXML(contentType)) {
+            // Convert JSON to XML if needed
+            body = convertBodyToXML(body);
+        }
+
         return { body, code, headers };
     },
     getHTTPBody: (body: any, headers?: Record<string, string>) => {
@@ -358,23 +369,48 @@ const BodyGenerators = {
             formUrlEncoded: () => {
                 const encoded = isPlainObject(body)
                     ? Object.entries(body)
-                          .map(([key, value]) => `${key}=${String(value)}`)
+                          .map(([key, value]) => `${key}=${stringifyOpenAPI(value)}`)
                           .join('&')
-                    : String(body);
-                return `"${encoded}"`;
+                    : stringifyOpenAPI(body);
+                return `"${encoded.replace(/"/g, "'")}"`;
             },
             text: () => `"${String(body)}"`,
-            xmlOrCsv: () => `"${stringifyOpenAPI(body).replace(/"/g, '')}"`,
+            xml: () => {
+                // Convert JSON to XML if needed
+                return `"${convertBodyToXML(body)}"`;
+            },
+            csv: () => `"${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();
-        }
+        if (isXML(contentType)) return typeHandlers.xml();
+        if (isCSV(contentType)) return typeHandlers.csv();
 
         return typeHandlers.default();
     },
 };
+
+/**
+ * Converts a body to XML format
+ */
+function convertBodyToXML(body: any): string {
+    // If body is already a string and looks like XML, return it as is
+    if (typeof body === 'string' && body.trim().startsWith('<')) {
+        return body;
+    }
+
+    // If body is not an object, try to parse it as JSON
+    if (typeof body !== 'object' || body === null) {
+        try {
+            body = JSON.parse(body);
+        } catch {
+            // If parsing fails, return the original body
+            return body;
+        }
+    }
+
+    return json2xml(body).replace(/"/g, '').replace(/\\n/g, '\n').replace(/\\t/g, '\t');
+}