@gitbook/react-openapi 1.0.1 → 1.0.2

package/dist/types.d.ts

@@ -4,6 +4,10 @@ export interface OpenAPIContextProps extends OpenAPIClientContext {
         code: string;
         syntax: string;
     }>;
+    renderHeading: (props: {
+        deprecated: boolean;
+        title: string;
+    }) => React.ReactNode;
     /** Spec url for the Scalar Api Client */
     specUrl: string;
 }

package/dist/utils.d.ts

@@ -1,7 +1,31 @@
-import type { AnyObject, OpenAPIV3 } from '@gitbook/openapi-parser';
-export declare function checkIsReference(input: unknown): input is OpenAPIV3.ReferenceObject;
+import type { AnyObject, OpenAPIV3, OpenAPIV3_1 } from '@gitbook/openapi-parser';
+export declare function checkIsReference(input: unknown): input is OpenAPIV3.ReferenceObject | OpenAPIV3_1.ReferenceObject;
 export declare function createStateKey(key: string, scope?: string): string;
 /**
  * Resolve the description of an object.
  */
 export declare function resolveDescription(object: AnyObject): string | undefined;
+/**
+ * Extract descriptions from an object.
+ */
+export declare function extractDescriptions(object: AnyObject): {
+    description: any;
+    "x-gitbook-description-html": any;
+};
+/**
+ * Resolve the first example from an object.
+ */
+export declare function resolveFirstExample(object: AnyObject): any;
+/**
+ * Resolve the schema of a parameter.
+ * Extract the description, example and deprecated from parameter.
+ */
+export declare function resolveParameterSchema(parameter: OpenAPIV3.ParameterBaseObject): OpenAPIV3.SchemaObject;
+/**
+ * Transform a parameter object to a property object.
+ */
+export declare function parameterToProperty(parameter: OpenAPIV3.ParameterObject | OpenAPIV3.ReferenceObject | OpenAPIV3_1.ReferenceObject): {
+    propertyName: string | undefined;
+    schema: OpenAPIV3.SchemaObject;
+    required: boolean | undefined;
+};

package/dist/utils.js

@@ -1,3 +1,14 @@
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 export function checkIsReference(input) {
     return typeof input === 'object' && !!input && '$ref' in input;
 }
@@ -8,9 +19,67 @@ export function createStateKey(key, scope) {
  * Resolve the description of an object.
  */
 export function resolveDescription(object) {
-    return 'x-description-html' in object && typeof object['x-description-html'] === 'string'
-        ? object['x-description-html']
+    return 'x-gitbook-description-html' in object &&
+        typeof object['x-gitbook-description-html'] === 'string'
+        ? object['x-gitbook-description-html'].trim()
         : typeof object.description === 'string'
-            ? object.description
+            ? object.description.trim()
             : undefined;
 }
+/**
+ * Extract descriptions from an object.
+ */
+export function extractDescriptions(object) {
+    var _a;
+    return _a = {
+            description: object.description
+        },
+        _a['x-gitbook-description-html'] = 'x-gitbook-description-html' in object
+            ? object['x-gitbook-description-html']
+            : undefined,
+        _a;
+}
+/**
+ * Resolve the first example from an object.
+ */
+export function resolveFirstExample(object) {
+    if ('examples' in object && typeof object.examples === 'object' && object.examples) {
+        var keys = Object.keys(object.examples);
+        var firstKey = keys[0];
+        if (firstKey && object.examples[firstKey]) {
+            return object.examples[firstKey];
+        }
+    }
+    if ('example' in object && object.example !== undefined) {
+        return object.example;
+    }
+    return undefined;
+}
+/**
+ * Resolve the schema of a parameter.
+ * Extract the description, example and deprecated from parameter.
+ */
+export function resolveParameterSchema(parameter) {
+    var schema = checkIsReference(parameter.schema) ? undefined : parameter.schema;
+    return __assign(__assign(__assign({}, extractDescriptions(parameter)), { example: resolveFirstExample(parameter), 
+        // Deprecated can be defined at the parameter level
+        deprecated: parameter.deprecated }), schema);
+}
+/**
+ * Transform a parameter object to a property object.
+ */
+export function parameterToProperty(parameter) {
+    var _a;
+    if (checkIsReference(parameter)) {
+        return {
+            propertyName: (_a = parameter.$ref) !== null && _a !== void 0 ? _a : 'Unknown ref',
+            schema: {},
+            required: undefined,
+        };
+    }
+    return {
+        propertyName: parameter.name,
+        schema: resolveParameterSchema(parameter),
+        required: parameter.required,
+    };
+}

package/package.json

@@ -8,7 +8,7 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "1.0.1",
+    "version": "1.0.2",
     "sideEffects": false,
     "dependencies": {
         "@gitbook/openapi-parser": "workspace:*",
@@ -16,6 +16,7 @@
         "@scalar/oas-utils": "^0.2.101",
         "clsx": "^2.1.1",
         "flatted": "^3.2.9",
+        "json-xml-parse": "^1.3.0",
         "react-aria-components": "^1.6.0",
         "react-aria": "^3.37.0",
         "usehooks-ts": "^3.1.0",

package/src/OpenAPICodeSample.tsx

@@ -58,7 +58,9 @@ export function OpenAPICodeSample(props: {
             (searchParams.size ? `?${searchParams.toString()}` : ''),
         method: data.method,
         body: requestBodyContent
-            ? generateMediaTypeExample(requestBodyContent[1], { onlyRequired: true })
+            ? generateMediaTypeExample(requestBodyContent[1], {
+                  omitEmptyAndOptionalProperties: true,
+              })
             : undefined,
         headers: {
             ...getSecurityHeaders(data.securities),

package/src/OpenAPIOperation.tsx

@@ -25,14 +25,17 @@ export function OpenAPIOperation(props: {
         blockKey: context.blockKey,
     };
 
-    const description = resolveDescription(operation)?.trim();
+    const description = resolveDescription(operation);
 
     return (
         <div className={clsx('openapi-operation', className)}>
-            <div className="openapi-summary" id={context.id}>
-                <h2 className="openapi-summary-title" data-deprecated={operation.deprecated}>
-                    {operation.summary}
-                </h2>
+            <div className="openapi-summary">
+                {operation.summary
+                    ? context.renderHeading({
+                          deprecated: operation.deprecated ?? false,
+                          title: operation.summary,
+                      })
+                    : null}
                 {operation.deprecated && <div className="openapi-deprecated">Deprecated</div>}
             </div>
             <div className="openapi-columns">

package/src/OpenAPIResponse.tsx

@@ -1,6 +1,6 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import { OpenAPISchemaProperties } from './OpenAPISchema';
-import { resolveDescription } from './utils';
+import { parameterToProperty, resolveDescription } from './utils';
 import type { OpenAPIClientContext } from './types';
 import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 
@@ -27,13 +27,11 @@ export function OpenAPIResponse(props: {
     return (
         <div className="openapi-response-body">
             {headers.length > 0 ? (
-                <OpenAPIDisclosure context={context} label={'Headers'}>
+                <OpenAPIDisclosure context={context} label="Headers">
                     <OpenAPISchemaProperties
-                        properties={headers.map(([name, header]) => ({
-                            propertyName: name,
-                            schema: header.schema ?? {},
-                            required: header.required,
-                        }))}
+                        properties={headers.map(([name, header]) => {
+                            return parameterToProperty({ name, ...header });
+                        })}
                         context={context}
                     />
                 </OpenAPIDisclosure>
@@ -41,11 +39,7 @@ export function OpenAPIResponse(props: {
             <div className="openapi-responsebody">
                 <OpenAPISchemaProperties
                     id={`response-${context.blockKey}`}
-                    properties={[
-                        {
-                            schema: mediaType.schema ?? {},
-                        },
-                    ]}
+                    properties={mediaType.schema ? [{ schema: mediaType.schema }] : []}
                     context={context}
                 />
             </div>

package/src/OpenAPIResponseExample.tsx

@@ -2,9 +2,9 @@ import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import { generateSchemaExample } from './generateSchemaExample';
 import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
 import { checkIsReference, createStateKey, resolveDescription } from './utils';
-import { stringifyOpenAPI } from './stringifyOpenAPI';
 import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
 import { InteractiveSection } from './InteractiveSection';
+import { json2xml } from './json2xml';
 
 /**
  * Display an example of the response content.
@@ -38,84 +38,51 @@ export function OpenAPIResponseExample(props: {
         return Number(a) - Number(b);
     });
 
-    const examples = responses
-        .map(([key, value]) => {
-            const responseObject = value;
-            const mediaTypeObject = (() => {
-                if (!responseObject.content) {
-                    return null;
-                }
-                const key = Object.keys(responseObject.content)[0];
-                return (
-                    responseObject.content['application/json'] ??
-                    (key ? responseObject.content[key] : null)
-                );
-            })();
-
-            if (!mediaTypeObject) {
+    const tabs = responses
+        .map(([key, responseObject]) => {
+            const description = resolveDescription(responseObject);
+
+            if (checkIsReference(responseObject)) {
                 return {
                     key: key,
                     label: key,
-                    description: resolveDescription(responseObject),
-                    body: <OpenAPIEmptyResponseExample />,
+                    description,
+                    body: (
+                        <OpenAPIExample
+                            example={getExampleFromReference(responseObject)}
+                            context={context}
+                            syntax="json"
+                        />
+                    ),
                 };
             }
 
-            const example = handleUnresolvedReference(
-                (() => {
-                    const { examples, example } = mediaTypeObject;
-                    if (examples) {
-                        const key = Object.keys(examples)[0];
-                        if (key) {
-                            // @TODO handle multiple examples
-                            const firstExample = examples[key];
-                            if (firstExample) {
-                                return firstExample;
-                            }
-                        }
-                    }
-
-                    if (example) {
-                        return { value: example };
-                    }
-
-                    const schema = mediaTypeObject.schema;
-                    if (!schema) {
-                        return null;
-                    }
-
-                    return { value: generateSchemaExample(schema) };
-                })(),
-            );
+            if (!responseObject.content || Object.keys(responseObject.content).length === 0) {
+                return {
+                    key: key,
+                    label: key,
+                    description,
+                    body: <OpenAPIEmptyResponseExample />,
+                };
+            }
 
             return {
                 key: key,
                 label: key,
                 description: resolveDescription(responseObject),
-                body: example?.value ? (
-                    <context.CodeBlock
-                        code={
-                            typeof example.value === 'string'
-                                ? example.value
-                                : stringifyOpenAPI(example.value, null, 2)
-                        }
-                        syntax="json"
-                    />
-                ) : (
-                    <OpenAPIEmptyResponseExample />
-                ),
+                body: <OpenAPIResponse context={context} content={responseObject.content} />,
             };
         })
         .filter((val): val is { key: string; label: string; body: any; description: string } =>
             Boolean(val),
         );
 
-    if (examples.length === 0) {
+    if (tabs.length === 0) {
         return null;
     }
 
     return (
-        <OpenAPITabs stateKey={createStateKey('response-example')} items={examples}>
+        <OpenAPITabs stateKey={createStateKey('response-example')} items={tabs}>
             <InteractiveSection header={<OpenAPITabsList />} className="openapi-response-example">
                 <OpenAPITabsPanels />
             </InteractiveSection>
@@ -123,6 +90,212 @@ export function OpenAPIResponseExample(props: {
     );
 }
 
+function OpenAPIResponse(props: {
+    context: OpenAPIContextProps;
+    content: {
+        [media: string]: OpenAPIV3.MediaTypeObject;
+    };
+}) {
+    const { context, content } = props;
+
+    const entries = Object.entries(content);
+    const firstEntry = entries[0];
+
+    if (!firstEntry) {
+        throw new Error('One media type is required');
+    }
+
+    if (entries.length === 1) {
+        const [mediaType, mediaTypeObject] = firstEntry;
+        return (
+            <OpenAPIResponseMediaType
+                context={context}
+                mediaType={mediaType}
+                mediaTypeObject={mediaTypeObject}
+            />
+        );
+    }
+
+    const tabs = entries.map((entry) => {
+        const [mediaType, mediaTypeObject] = entry;
+        return {
+            key: mediaType,
+            label: mediaType,
+            body: (
+                <OpenAPIResponseMediaType
+                    context={context}
+                    mediaType={mediaType}
+                    mediaTypeObject={mediaTypeObject}
+                />
+            ),
+        };
+    });
+
+    return (
+        <OpenAPITabs stateKey={createStateKey('response-media-types')} items={tabs}>
+            <InteractiveSection
+                header={<OpenAPITabsList />}
+                className="openapi-response-media-types"
+            >
+                <OpenAPITabsPanels />
+            </InteractiveSection>
+        </OpenAPITabs>
+    );
+}
+
+function OpenAPIResponseMediaType(props: {
+    mediaTypeObject: OpenAPIV3.MediaTypeObject;
+    mediaType: string;
+    context: OpenAPIContextProps;
+}) {
+    const { mediaTypeObject, mediaType } = props;
+    const examples = getExamplesFromMediaTypeObject({ mediaTypeObject, mediaType });
+    const syntax = getSyntaxFromMediaType(mediaType);
+    const firstExample = examples[0];
+
+    if (!firstExample) {
+        return <OpenAPIEmptyResponseExample />;
+    }
+
+    if (examples.length === 1) {
+        return (
+            <OpenAPIExample
+                example={firstExample.example}
+                context={props.context}
+                syntax={syntax}
+            />
+        );
+    }
+
+    const tabs = examples.map((example) => {
+        return {
+            key: example.key,
+            label: example.example.summary || example.key,
+            body: (
+                <OpenAPIExample
+                    example={firstExample.example}
+                    context={props.context}
+                    syntax={syntax}
+                />
+            ),
+        };
+    });
+
+    return (
+        <OpenAPITabs stateKey={createStateKey('response-media-type-examples')} items={tabs}>
+            <InteractiveSection
+                header={<OpenAPITabsList />}
+                className="openapi-response-media-type-examples"
+            >
+                <OpenAPITabsPanels />
+            </InteractiveSection>
+        </OpenAPITabs>
+    );
+}
+
+/**
+ * Display an example.
+ */
+function OpenAPIExample(props: {
+    example: OpenAPIV3.ExampleObject;
+    context: OpenAPIContextProps;
+    syntax: string;
+}) {
+    const { example, context, syntax } = props;
+    const code = stringifyExample({ example, xml: syntax === 'xml' });
+
+    if (code === null) {
+        return <OpenAPIEmptyResponseExample />;
+    }
+
+    return <context.CodeBlock code={code} syntax={syntax} />;
+}
+
+function stringifyExample(args: { example: OpenAPIV3.ExampleObject; xml: boolean }): string | null {
+    const { example, xml } = args;
+
+    if (!example.value) {
+        return null;
+    }
+
+    if (typeof example.value === 'string') {
+        return example.value;
+    }
+
+    if (xml) {
+        return json2xml(example.value);
+    }
+
+    return JSON.stringify(example.value, null, 2);
+}
+
+/**
+ * Get the syntax from a media type.
+ */
+function getSyntaxFromMediaType(mediaType: string): string {
+    if (mediaType.includes('json')) {
+        return 'json';
+    }
+
+    if (mediaType === 'application/xml') {
+        return 'xml';
+    }
+
+    return 'text';
+}
+
+/**
+ * Get examples from a media type object.
+ */
+function getExamplesFromMediaTypeObject(args: {
+    mediaType: string;
+    mediaTypeObject: OpenAPIV3.MediaTypeObject;
+}): { key: string; example: OpenAPIV3.ExampleObject }[] {
+    const { mediaTypeObject, mediaType } = args;
+    if (mediaTypeObject.examples) {
+        return Object.entries(mediaTypeObject.examples).map(([key, example]) => {
+            return {
+                key,
+                example: checkIsReference(example) ? getExampleFromReference(example) : example,
+            };
+        });
+    }
+
+    if (mediaTypeObject.example) {
+        return [{ key: 'default', example: { value: mediaTypeObject.example } }];
+    }
+
+    if (mediaTypeObject.schema) {
+        if (mediaType === 'application/xml') {
+            // @TODO normally we should use the name of the schema but we don't have it
+            // fix it when we got the reference name
+            const root = mediaTypeObject.schema.xml?.name ?? 'object';
+            return [
+                {
+                    key: 'default',
+                    example: {
+                        value: {
+                            [root]: generateSchemaExample(mediaTypeObject.schema, {
+                                xml: mediaType === 'application/xml',
+                            }),
+                        },
+                    },
+                },
+            ];
+        }
+        return [
+            {
+                key: 'default',
+                example: { value: generateSchemaExample(mediaTypeObject.schema) },
+            },
+        ];
+    }
+    return [];
+}
+
+/**
+ * Empty response example.
+ */
 function OpenAPIEmptyResponseExample() {
     return (
         <pre className="openapi-response-example-empty">
@@ -131,15 +304,9 @@ function OpenAPIEmptyResponseExample() {
     );
 }
 
-function handleUnresolvedReference(
-    input: OpenAPIV3.ExampleObject | null,
-): OpenAPIV3.ExampleObject | null {
-    const isReference = checkIsReference(input?.value);
-
-    if (isReference) {
-        // If we find a reference that wasn't resolved or needed to be resolved externally, render out the URL
-        return { value: input.value.$ref };
-    }
-
-    return input;
+/**
+ * Generate an example from a reference object.
+ */
+function getExampleFromReference(ref: OpenAPIV3.ReferenceObject): OpenAPIV3.ExampleObject {
+    return { summary: 'Unresolved reference', value: { $ref: ref.$ref } };
 }

package/src/OpenAPISchema.tsx

@@ -13,8 +13,8 @@ import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 type CircularRefsIds = Map<OpenAPIV3.SchemaObject, string>;
 
 export interface OpenAPISchemaPropertyEntry {
-    propertyName?: string;
-    required?: boolean;
+    propertyName?: string | undefined;
+    required?: boolean | undefined;
     schema: OpenAPIV3.SchemaObject;
 }
 
@@ -47,7 +47,7 @@ export function OpenAPISchemaProperty(
         ? null
         : getSchemaAlternatives(schema, new Set(circularRefs.keys()));
 
-    if ((properties && !!properties.length) || schema.type === 'object') {
+    if ((properties && properties.length > 0) || schema.type === 'object') {
         return (
             <InteractiveSection id={id} className={clsx('openapi-schema', className)}>
                 <OpenAPISchemaPresentation {...props} />
@@ -397,7 +397,7 @@ export function getSchemaTitle(
     let type = 'any';
 
     if (schema.enum) {
-        type = '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) {
         type = `${getSchemaTitle(schema.items)}[]`;
@@ -407,7 +407,7 @@ export function getSchemaTitle(
         type = schema.type ?? 'object';
 
         if (schema.format) {
-            type += ` ${schema.format}`;
+            type += ` · ${schema.format}`;
         }
     } else if ('anyOf' in schema) {
         type = 'any of';
@@ -419,8 +419,20 @@ export function getSchemaTitle(
         type = 'not';
     }
 
+    if (schema.minimum || schema.minLength) {
+        type += ` · min: ${schema.minimum || schema.minLength}`;
+    }
+
+    if (schema.maximum || schema.maxLength) {
+        type += ` · max: ${schema.maximum || schema.maxLength}`;
+    }
+
+    if (schema.default) {
+        type += ` · default: ${schema.default}`;
+    }
+
     if (schema.nullable) {
-        type = `nullable ${type}`;
+        type = `${type} | nullable`;
     }
 
     return type;

package/src/OpenAPISpec.tsx

@@ -8,7 +8,7 @@ import { OpenAPIResponses } from './OpenAPIResponses';
 import { OpenAPISchemaProperties } from './OpenAPISchema';
 import { OpenAPISecurities } from './OpenAPISecurities';
 import type { OpenAPIClientContext, OpenAPIOperationData } from './types';
-import { resolveDescription } from './utils';
+import { parameterToProperty } from './utils';
 
 /**
  * Client component to render the spec for the request and response.
@@ -38,22 +38,7 @@ export function OpenAPISpec(props: { data: OpenAPIOperationData; context: OpenAP
                         header={group.label}
                     >
                         <OpenAPISchemaProperties
-                            properties={group.parameters.map((parameter) => {
-                                const description = resolveDescription(parameter);
-                                return {
-                                    propertyName: parameter.name,
-                                    schema: {
-                                        // Description of the parameter is defined at the parameter level
-                                        // we use display it if the schema doesn't override it
-                                        description: description,
-                                        example: parameter.example,
-                                        // Deprecated can be defined at the parameter level
-                                        deprecated: parameter.deprecated,
-                                        ...(parameter.schema ?? {}),
-                                    },
-                                    required: parameter.required,
-                                };
-                            })}
+                            properties={group.parameters.map(parameterToProperty)}
                             context={context}
                         />
                     </InteractiveSection>