@gitbook/react-openapi 1.0.5 → 1.1.0

package/dist/types.d.ts

@@ -51,3 +51,11 @@ export interface OpenAPIOperationData extends OpenAPICustomSpecProperties {
     /** Securities that should be used for this operation */
     securities: [string, OpenAPIV3.SecuritySchemeObject][];
 }
+export type OpenAPIModel = {
+    name: string;
+    schema: OpenAPIV3.SchemaObject;
+};
+export interface OpenAPIModelsData {
+    /** Components schemas to be used for models */
+    models: OpenAPIModel[];
+}

package/dist/utils.js

@@ -9,17 +9,25 @@ var __assign = (this && this.__assign) || function () {
     };
     return __assign.apply(this, arguments);
 };
+import { stringifyOpenAPI } from './stringifyOpenAPI';
 export function checkIsReference(input) {
     return typeof input === 'object' && !!input && '$ref' in input;
 }
 export function createStateKey(key, scope) {
     return scope ? "".concat(scope, "_").concat(key) : key;
 }
+/**
+ * Check if an object has a description. Either at the root level or in items.
+ */
+function hasDescription(object) {
+    return 'description' in object || 'x-gitbook-description-html' in object;
+}
 /**
  * Resolve the description of an object.
  */
 export function resolveDescription(object) {
-    if ('items' in object && object.items) {
+    // If the object has items and has a description, we resolve the description from items
+    if ('items' in object && typeof object.items === 'object' && hasDescription(object.items)) {
         return resolveDescription(object.items);
     }
     return 'x-gitbook-description-html' in object &&
@@ -51,8 +59,13 @@ export function resolveFirstExample(object) {
             return object.examples[firstKey];
         }
     }
-    if ('example' in object && object.example !== undefined) {
-        return object.example;
+    // Resolve top level example first
+    if (shouldDisplayExample(object)) {
+        return formatExample(object.example);
+    }
+    // Resolve example from items if it exists
+    if (object.items && typeof object.items === 'object') {
+        return formatExample(object.items.example);
     }
     return undefined;
 }
@@ -84,3 +97,29 @@ export function parameterToProperty(parameter) {
         required: parameter.required,
     };
 }
+/**
+ * Format the example of a schema.
+ */
+function formatExample(example) {
+    if (typeof example === 'string') {
+        return example
+            .replace(/\n/g, ' ') // Replace newlines with spaces
+            .replace(/\s+/g, ' ') // Collapse multiple spaces/newlines into a single space
+            .replace(/([\{\}:,])\s+/g, '$1 ') // Ensure a space after {, }, :, and ,
+            .replace(/\s+([\{\}:,])/g, ' $1') // Ensure a space before {, }, :, and ,
+            .trim();
+    }
+    return stringifyOpenAPI(example);
+}
+/**
+ * Check if an example should be displayed.
+ */
+function shouldDisplayExample(schema) {
+    return ((typeof schema.example === 'string' && !!schema.example) ||
+        typeof schema.example === 'number' ||
+        typeof schema.example === 'boolean' ||
+        (Array.isArray(schema.example) && schema.example.length > 0) ||
+        (typeof schema.example === 'object' &&
+            schema.example !== null &&
+            Object.keys(schema.example).length > 0));
+}

package/package.json

@@ -8,12 +8,12 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "1.0.5",
+    "version": "1.1.0",
     "sideEffects": false,
     "dependencies": {
         "@gitbook/openapi-parser": "workspace:*",
-        "@scalar/api-client-react": "1.0.87",
-        "@scalar/oas-utils": "^0.2.101",
+        "@scalar/api-client-react": "^1.1.36",
+        "@scalar/oas-utils": "^0.2.110",
         "clsx": "^2.1.1",
         "flatted": "^3.2.9",
         "json-xml-parse": "^1.3.0",

package/src/OpenAPIDisclosure.tsx

@@ -1,52 +1,44 @@
 'use client';
-import type React from 'react';
-import { useRef } from 'react';
-import { mergeProps, useButton, useDisclosure, useFocusRing } from 'react-aria';
-import { useDisclosureState } from 'react-stately';
+import { useState } from 'react';
+import { Button, Disclosure, DisclosurePanel, Heading } from 'react-aria-components';
 import type { OpenAPIClientContext } from './types';
 
-interface Props {
-    context: OpenAPIClientContext;
-    children: React.ReactNode;
-    label?: string;
-}
-
 /**
  * Display an interactive OpenAPI disclosure.
- * The label is optional and defaults to "child attributes".
  */
-export function OpenAPIDisclosure({ context, children, label }: Props): React.JSX.Element {
-    const state = useDisclosureState({});
-    const panelRef = useRef<HTMLDivElement | null>(null);
-    const triggerRef = useRef<HTMLButtonElement | null>(null);
-    const { buttonProps: triggerProps, panelProps } = useDisclosure({}, state, panelRef);
-    const { buttonProps } = useButton(triggerProps, triggerRef);
-    const { isFocusVisible, focusProps } = useFocusRing();
+export function OpenAPIDisclosure(props: {
+    context: OpenAPIClientContext;
+    children: React.ReactNode;
+    label: string;
+}): React.JSX.Element {
+    const { context, children, label } = props;
+    const [isExpanded, setIsExpanded] = useState(false);
 
     return (
-        <div className="openapi-disclosure">
-            <button
-                ref={triggerRef}
-                {...mergeProps(buttonProps, focusProps)}
-                slot="trigger"
-                className="openapi-disclosure-trigger"
-                style={{
-                    outline: isFocusVisible
-                        ? '2px solid rgb(var(--primary-color-500) / 0.4)'
-                        : 'none',
-                }}
-            >
-                {context.icons.plus}
-                <span>
-                    {`${state.isExpanded ? 'Hide' : 'Show'} ${label ? label : 'child attributes'}`}
-                </span>
-            </button>
-
-            {state.isExpanded && (
-                <div ref={panelRef} {...panelProps} className="openapi-disclosure-panel">
-                    {children}
-                </div>
-            )}
-        </div>
+        <Disclosure
+            className="openapi-disclosure"
+            isExpanded={isExpanded}
+            onExpandedChange={setIsExpanded}
+        >
+            <Heading>
+                <Button
+                    slot="trigger"
+                    className="openapi-disclosure-trigger"
+                    style={({ isFocusVisible }) => ({
+                        outline: isFocusVisible
+                            ? '2px solid rgb(var(--primary-color-500) / 0.4)'
+                            : 'none',
+                    })}
+                >
+                    {context.icons.plus}
+                    <span>
+                        {isExpanded ? 'Hide' : 'Show'} {label}
+                    </span>
+                </Button>
+            </Heading>
+            <DisclosurePanel className="openapi-disclosure-panel">
+                {isExpanded ? children : null}
+            </DisclosurePanel>
+        </Disclosure>
     );
 }

package/src/OpenAPIDisclosureGroup.tsx

@@ -19,7 +19,7 @@ type TDisclosureGroup = {
     label: string | React.ReactNode;
     tabs?: {
         id: string;
-        label: string | React.ReactNode;
+        label?: string | React.ReactNode;
         body?: React.ReactNode;
     }[];
 };
@@ -121,7 +121,7 @@ function DisclosureItem(props: { group: TDisclosureGroup; icon?: React.ReactNode
                                     </option>
                                 ))}
                             </select>
-                        ) : group.tabs[0] ? (
+                        ) : group.tabs[0]?.label ? (
                             <span>{group.tabs[0].label}</span>
                         ) : null}
                     </div>

package/src/OpenAPIPath.tsx

@@ -1,3 +1,4 @@
+import type { OpenAPIV3_1 } from '@gitbook/openapi-parser';
 import type React from 'react';
 import { ScalarApiButton } from './ScalarApiButton';
 import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
@@ -12,6 +13,7 @@ export function OpenAPIPath(props: {
     const { data, context } = props;
     const { method, path } = data;
     const { specUrl } = context;
+    const hideTryItPanel = data['x-hideTryItPanel'] || data.operation['x-hideTryItPanel'];
 
     return (
         <div className="openapi-path">
@@ -19,13 +21,17 @@ export function OpenAPIPath(props: {
             <div className="openapi-path-title" data-deprecated={data.operation.deprecated}>
                 <p>{formatPath(path)}</p>
             </div>
-            {data['x-hideTryItPanel'] || data.operation['x-hideTryItPanel'] ? null : (
+            {!hideTryItPanel && validateHttpMethod(method) && (
                 <ScalarApiButton method={method} path={path} specUrl={specUrl} />
             )}
         </div>
     );
 }
 
+function validateHttpMethod(method: string): method is OpenAPIV3_1.HttpMethods {
+    return ['get', 'post', 'put', 'delete', 'patch', 'head', 'options', 'trace'].includes(method);
+}
+
 // Format the path to highlight placeholders
 function formatPath(path: string) {
     // Matches placeholders like {id}, {userId}, etc.

package/src/OpenAPISchema.test.ts

@@ -23,18 +23,15 @@ describe('getSchemaAlternatives', () => {
                 ],
             })
         ).toEqual([
-            [
-                {
-                    type: 'number',
-                },
-                {
-                    type: 'boolean',
-                },
-                {
-                    type: 'string',
-                },
-            ],
-            undefined,
+            {
+                type: 'number',
+            },
+            {
+                type: 'boolean',
+            },
+            {
+                type: 'string',
+            },
         ]);
     });
 
@@ -58,22 +55,19 @@ describe('getSchemaAlternatives', () => {
                 ],
             })
         ).toEqual([
-            [
-                {
-                    allOf: [
-                        {
-                            type: 'number',
-                        },
-                        {
-                            type: 'boolean',
-                        },
-                    ],
-                },
-                {
-                    type: 'string',
-                },
-            ],
-            undefined,
+            {
+                allOf: [
+                    {
+                        type: 'number',
+                    },
+                    {
+                        type: 'boolean',
+                    },
+                ],
+            },
+            {
+                type: 'string',
+            },
         ]);
     });
 
@@ -89,13 +83,10 @@ describe('getSchemaAlternatives', () => {
         a.anyOf?.push(a);
 
         expect(getSchemaAlternatives(a)).toEqual([
-            [
-                {
-                    type: 'string',
-                },
-                a,
-            ],
-            undefined,
+            {
+                type: 'string',
+            },
+            a,
         ]);
     });
 });