@gitbook/react-openapi 1.0.2 → 1.0.4

package/dist/types.d.ts

@@ -1,13 +1,25 @@
 import type { OpenAPICustomOperationProperties, OpenAPICustomSpecProperties, OpenAPIV3 } from '@gitbook/openapi-parser';
 export interface OpenAPIContextProps extends OpenAPIClientContext {
-    CodeBlock: React.ComponentType<{
+    /**
+     * 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/dist/util/server.d.ts

@@ -0,0 +1,9 @@
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+/**
+ * Get the default URL for the server.
+ */
+export declare function getDefaultServerURL(servers: OpenAPIV3.ServerObject[]): string;
+/**
+ * Interpolate the server URL with the default values of the variables.
+ */
+export declare function interpolateServerURL(server: OpenAPIV3.ServerObject): string;

package/dist/util/server.js

@@ -0,0 +1,44 @@
+/**
+ * Get the default URL for the server.
+ */
+export function getDefaultServerURL(servers) {
+    var 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) {
+    var _a;
+    var parts = parseServerURL((_a = server === null || server === void 0 ? void 0 : server.url) !== null && _a !== void 0 ? _a : '');
+    return parts
+        .map(function (part) {
+        var _a, _b, _c;
+        if (part.kind === 'text') {
+            return part.text;
+        }
+        return (_c = (_b = (_a = server.variables) === null || _a === void 0 ? void 0 : _a[part.name]) === null || _b === void 0 ? void 0 : _b.default) !== null && _c !== void 0 ? _c : "{".concat(part.name, "}");
+    })
+        .join('');
+}
+function parseServerURL(url) {
+    var parts = url.split(/{([^}]+)}/g);
+    var result = [];
+    for (var i = 0; i < parts.length; i++) {
+        var 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;
+}

package/dist/utils.d.ts

@@ -4,13 +4,13 @@ export declare function createStateKey(key: string, scope?: string): string;
 /**
  * Resolve the description of an object.
  */
-export declare function resolveDescription(object: AnyObject): string | undefined;
+export declare function resolveDescription(object: OpenAPIV3.SchemaObject | AnyObject): string | undefined;
 /**
  * Extract descriptions from an object.
  */
 export declare function extractDescriptions(object: AnyObject): {
     description: any;
-    "x-gitbook-description-html": any;
+    'x-gitbook-description-html': any;
 };
 /**
  * Resolve the first example from an object.

package/dist/utils.js

@@ -19,6 +19,9 @@ export function createStateKey(key, scope) {
  * Resolve the description of an object.
  */
 export function resolveDescription(object) {
+    if ('items' in object && object.items) {
+        return resolveDescription(object.items);
+    }
     return 'x-gitbook-description-html' in object &&
         typeof object['x-gitbook-description-html'] === 'string'
         ? object['x-gitbook-description-html'].trim()
@@ -30,14 +33,12 @@ export function resolveDescription(object) {
  * 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
+    return {
+        description: object.description,
+        'x-gitbook-description-html': 'x-gitbook-description-html' in object
             ? object['x-gitbook-description-html']
             : undefined,
-        _a;
+    };
 }
 /**
  * Resolve the first example from an object.

package/package.json

@@ -8,7 +8,7 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "1.0.2",
+    "version": "1.0.4",
     "sideEffects": false,
     "dependencies": {
         "@gitbook/openapi-parser": "workspace:*",
@@ -30,16 +30,11 @@
         "react": "*"
     },
     "scripts": {
-        "build": "tsc --project tsconfig.build.json",
+        "build": "rm -rf ./dist && tsc --project tsconfig.build.json",
         "typecheck": "tsc --noEmit",
         "unit": "bun test",
         "dev": "bun run build -- --watch",
         "clean": "rm -rf ./dist"
     },
-    "files": [
-        "dist",
-        "src",
-        "README.md",
-        "CHANGELOG.md"
-    ]
+    "files": ["dist", "src", "README.md", "CHANGELOG.md"]
 }

package/src/InteractiveSection.tsx

@@ -69,7 +69,7 @@ export function InteractiveSection(props: {
                 'openapi-section',
                 toggeable ? 'openapi-section-toggeable' : null,
                 className,
-                toggeable ? `${className}-${state.isExpanded ? 'opened' : 'closed'}` : null,
+                toggeable ? `${className}-${state.isExpanded ? 'opened' : 'closed'}` : null
             )}
         >
             {header ? (
@@ -84,7 +84,7 @@ export function InteractiveSection(props: {
                     <div
                         className={clsx(
                             'openapi-section-header-content',
-                            `${className}-header-content`,
+                            `${className}-header-content`
                         )}
                     >
                         {(children || selectedTab?.body) && toggeable ? (
@@ -106,7 +106,7 @@ export function InteractiveSection(props: {
                     <div
                         className={clsx(
                             'openapi-section-header-controls',
-                            `${className}-header-controls`,
+                            `${className}-header-controls`
                         )}
                         onClick={(event) => {
                             event.stopPropagation();
@@ -117,7 +117,7 @@ export function InteractiveSection(props: {
                                 className={clsx(
                                     'openapi-section-select',
                                     'openapi-select',
-                                    `${className}-tabs-select`,
+                                    `${className}-tabs-select`
                                 )}
                                 value={selectedTab?.key ?? ''}
                                 onChange={(event) => {

package/src/OpenAPICodeSample.tsx

@@ -1,12 +1,11 @@
-import { CodeSampleInput, codeSampleGenerators } from './code-samples';
-import { generateMediaTypeExample, generateSchemaExample } from './generateSchemaExample';
 import { InteractiveSection } from './InteractiveSection';
-import { getServersURL } from './OpenAPIServerURL';
-import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
-import { createStateKey } from './utils';
-import { stringifyOpenAPI } from './stringifyOpenAPI';
 import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
-import { checkIsReference } from './utils';
+import { type CodeSampleInput, codeSampleGenerators } from './code-samples';
+import { generateMediaTypeExample, generateSchemaExample } from './generateSchemaExample';
+import { stringifyOpenAPI } from './stringifyOpenAPI';
+import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
+import { getDefaultServerURL } from './util/server';
+import { checkIsReference, createStateKey } from './utils';
 
 /**
  * Display code samples to execute the operation.
@@ -37,7 +36,7 @@ export function OpenAPICodeSample(props: {
             if (example !== undefined && param.name) {
                 searchParams.append(
                     param.name,
-                    String(Array.isArray(example) ? example[0] : example),
+                    String(Array.isArray(example) ? example[0] : example)
                 );
             }
         }
@@ -53,15 +52,11 @@ export function OpenAPICodeSample(props: {
 
     const input: CodeSampleInput = {
         url:
-            getServersURL(data.servers) +
+            getDefaultServerURL(data.servers) +
             data.path +
             (searchParams.size ? `?${searchParams.toString()}` : ''),
         method: data.method,
-        body: requestBodyContent
-            ? generateMediaTypeExample(requestBodyContent[1], {
-                  omitEmptyAndOptionalProperties: true,
-              })
-            : undefined,
+        body: requestBodyContent ? generateMediaTypeExample(requestBodyContent[1]) : undefined,
         headers: {
             ...getSecurityHeaders(data.securities),
             ...headersObject,
@@ -76,7 +71,10 @@ export function OpenAPICodeSample(props: {
     const autoCodeSamples = codeSampleGenerators.map((generator) => ({
         key: `default-${generator.id}`,
         label: generator.label,
-        body: <context.CodeBlock code={generator.generate(input)} syntax={generator.syntax} />,
+        body: context.renderCodeBlock({
+            code: generator.generate(input),
+            syntax: generator.syntax,
+        }),
     }));
 
     // Use custom samples if defined
@@ -96,10 +94,13 @@ export function OpenAPICodeSample(props: {
                         typeof sample.lang === 'string'
                     );
                 })
-                .map((sample) => ({
-                    key: `redocly-${sample.lang}`,
+                .map((sample, index) => ({
+                    key: `redocly-${sample.lang}-${index}`,
                     label: sample.label,
-                    body: <context.CodeBlock code={sample.source} syntax={sample.lang} />,
+                    body: context.renderCodeBlock({
+                        code: sample.source,
+                        syntax: sample.lang,
+                    }),
                 }));
         }
     });
@@ -147,7 +148,7 @@ function getSecurityHeaders(securities: OpenAPIOperationData['securities']): {
             }
 
             return {
-                Authorization: scheme + ' ' + format,
+                Authorization: `${scheme} ${format}`,
             };
         }
         case 'apiKey': {

package/src/OpenAPIDisclosure.tsx

@@ -1,7 +1,8 @@
+import type React from 'react';
 import { useRef } from 'react';
-import type { OpenAPIClientContext } from './types';
 import { mergeProps, useButton, useDisclosure, useFocusRing } from 'react-aria';
 import { useDisclosureState } from 'react-stately';
+import type { OpenAPIClientContext } from './types';
 
 interface Props {
     context: OpenAPIClientContext;
@@ -13,7 +14,7 @@ interface Props {
  * Display an interactive OpenAPI disclosure.
  * The label is optional and defaults to "child attributes".
  */
-export function OpenAPIDisclosure({ context, children, label }: Props): JSX.Element {
+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);
@@ -36,7 +37,7 @@ export function OpenAPIDisclosure({ context, children, label }: Props): JSX.Elem
             >
                 {context.icons.plus}
                 <span>
-                    {`${state.isExpanded ? 'Hide' : 'Show'} ${label ? label : `child attributes`}`}
+                    {`${state.isExpanded ? 'Hide' : 'Show'} ${label ? label : 'child attributes'}`}
                 </span>
             </button>
 

package/src/OpenAPIDisclosureGroup.tsx

@@ -13,14 +13,14 @@ type TDisclosureGroup = {
     }[];
 };
 
+import { createContext, useContext, useRef, useState } from 'react';
 import { mergeProps, useButton, useDisclosure, useFocusRing, useId } from 'react-aria';
 import {
-    DisclosureGroupProps,
-    DisclosureGroupState,
+    type DisclosureGroupProps,
+    type DisclosureGroupState,
     useDisclosureGroupState,
     useDisclosureState,
 } from 'react-stately';
-import { createContext, useContext, useRef, useState } from 'react';
 
 const DisclosureGroupStateContext = createContext<DisclosureGroupState | null>(null);
 
@@ -67,7 +67,7 @@ function DisclosureItem(props: { group: TDisclosureGroup; icon?: React.ReactNode
             isDisabled,
         },
         state,
-        panelRef,
+        panelRef
     );
     const { buttonProps } = useButton(triggerProps, triggerRef);
     const { isFocusVisible, focusProps } = useFocusRing();
@@ -119,7 +119,7 @@ function DisclosureItem(props: { group: TDisclosureGroup; icon?: React.ReactNode
                                     </option>
                                 ))}
                             </select>
-                        ) : !!group.tabs[0] ? (
+                        ) : group.tabs[0] ? (
                             <span>{group.tabs[0].label}</span>
                         ) : null}
                     </div>

package/src/OpenAPIOperation.tsx

@@ -1,11 +1,12 @@
 import clsx from 'clsx';
 
+import type { OpenAPICustomOperationProperties, OpenAPIV3 } from '@gitbook/openapi-parser';
 import { Markdown } from './Markdown';
 import { OpenAPICodeSample } from './OpenAPICodeSample';
+import { OpenAPIPath } from './OpenAPIPath';
 import { OpenAPIResponseExample } from './OpenAPIResponseExample';
 import { OpenAPISpec } from './OpenAPISpec';
 import type { OpenAPIClientContext, OpenAPIContextProps, OpenAPIOperationData } from './types';
-import { OpenAPIPath } from './OpenAPIPath';
 import { resolveDescription } from './utils';
 
 /**
@@ -25,11 +26,9 @@ export function OpenAPIOperation(props: {
         blockKey: context.blockKey,
     };
 
-    const description = resolveDescription(operation);
-
     return (
         <div className={clsx('openapi-operation', className)}>
-            <div className="openapi-summary">
+            <div className="openapi-summary" id={operation.summary ? undefined : context.id}>
                 {operation.summary
                     ? context.renderHeading({
                           deprecated: operation.deprecated ?? false,
@@ -46,14 +45,10 @@ export function OpenAPIOperation(props: {
                             <span className="openapi-deprecated-sunset-date">
                                 {operation['x-deprecated-sunset']}
                             </span>
-                            {`.`}
-                        </div>
-                    ) : null}
-                    {description ? (
-                        <div className="openapi-intro">
-                            <Markdown className="openapi-description" source={description} />
+                            {'.'}
                         </div>
                     ) : null}
+                    <OpenAPIOperationDescription operation={operation} context={context} />
                     <OpenAPIPath data={data} context={context} />
                     <OpenAPISpec data={data} context={clientContext} />
                 </div>
@@ -67,3 +62,30 @@ export function OpenAPIOperation(props: {
         </div>
     );
 }
+
+function OpenAPIOperationDescription(props: {
+    operation: OpenAPIV3.OperationObject<OpenAPICustomOperationProperties>;
+    context: OpenAPIContextProps;
+}) {
+    const { operation } = props;
+    if (operation['x-gitbook-description-document']) {
+        return (
+            <div className="openapi-intro">
+                {props.context.renderDocument({
+                    document: operation['x-gitbook-description-document'],
+                })}
+            </div>
+        );
+    }
+
+    const description = resolveDescription(operation);
+    if (!description) {
+        return null;
+    }
+
+    return (
+        <div className="openapi-intro">
+            <Markdown className="openapi-description" source={description} />
+        </div>
+    );
+}

package/src/OpenAPIOperationContext.tsx

@@ -20,7 +20,7 @@ const OpenAPIOperationContext = createContext<OpenAPIOperationContextValue>({
  * Provider for the OpenAPIOperationContext.
  */
 export function OpenAPIOperationContextProvider(
-    props: React.PropsWithChildren<Partial<OpenAPIOperationContextValue>>,
+    props: React.PropsWithChildren<Partial<OpenAPIOperationContextValue>>
 ) {
     const { children } = props;
 

package/src/OpenAPIPath.tsx

@@ -1,5 +1,6 @@
+import type React from 'react';
 import { ScalarApiButton } from './ScalarApiButton';
-import type { OpenAPIOperationData, OpenAPIContextProps } from './types';
+import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
 
 /**
  * Display the path of an operation.
@@ -7,7 +8,7 @@ import type { OpenAPIOperationData, OpenAPIContextProps } from './types';
 export function OpenAPIPath(props: {
     data: OpenAPIOperationData;
     context: OpenAPIContextProps;
-}): JSX.Element {
+}) {
     const { data, context } = props;
     const { method, path } = data;
     const { specUrl } = context;
@@ -30,7 +31,7 @@ function formatPath(path: string) {
     // Matches placeholders like {id}, {userId}, etc.
     const regex = /\{(\w+)\}/g;
 
-    const parts: (string | JSX.Element)[] = [];
+    const parts: (string | React.JSX.Element)[] = [];
     let lastIndex = 0;
 
     // Replace placeholders with <em> tags
@@ -48,17 +49,17 @@ function formatPath(path: string) {
     const formattedPath = parts.reduce(
         (acc, part, index) => {
             if (typeof part === 'string' && index > 0 && part === '/') {
-                return [
-                    ...acc,
+                acc.push(
                     <span className="openapi-path-separator" key={`sep-${index}`}>
                         /
-                    </span>,
-                    part,
-                ];
+                    </span>
+                );
             }
-            return [...acc, part];
+
+            acc.push(part);
+            return acc;
         },
-        [] as (string | JSX.Element)[],
+        [] as (string | React.JSX.Element)[]
     );
 
     return <span>{formattedPath}</span>;

package/src/OpenAPIRequestBody.tsx

@@ -1,7 +1,7 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import { InteractiveSection } from './InteractiveSection';
 import { OpenAPIRootSchema } from './OpenAPISchema';
 import type { OpenAPIClientContext } from './types';
-import { InteractiveSection } from './InteractiveSection';
 import { checkIsReference } from './utils';
 
 /**
@@ -33,7 +33,7 @@ export function OpenAPIRequestBody(props: {
                             />
                         ),
                     };
-                },
+                }
             )}
         />
     );

package/src/OpenAPIResponse.tsx

@@ -1,8 +1,8 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 import { OpenAPISchemaProperties } from './OpenAPISchema';
-import { parameterToProperty, resolveDescription } from './utils';
 import type { OpenAPIClientContext } from './types';
-import { OpenAPIDisclosure } from './OpenAPIDisclosure';
+import { parameterToProperty, resolveDescription } from './utils';
 
 /**
  * Display an interactive response body.
@@ -14,7 +14,7 @@ export function OpenAPIResponse(props: {
 }) {
     const { response, context, mediaType } = props;
     const headers = Object.entries(response.headers ?? {}).map(
-        ([name, header]) => [name, header ?? {}] as const,
+        ([name, header]) => [name, header ?? {}] as const
     );
     const content = Object.entries(mediaType.schema ?? {});
 

package/src/OpenAPIResponseExample.tsx

@@ -1,10 +1,11 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import { InteractiveSection } from './InteractiveSection';
+import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
 import { generateSchemaExample } from './generateSchemaExample';
+import { json2xml } from './json2xml';
+import { stringifyOpenAPI } from './stringifyOpenAPI';
 import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
 import { checkIsReference, createStateKey, resolveDescription } from './utils';
-import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
-import { InteractiveSection } from './InteractiveSection';
-import { json2xml } from './json2xml';
 
 /**
  * Display an example of the response content.
@@ -74,7 +75,7 @@ export function OpenAPIResponseExample(props: {
             };
         })
         .filter((val): val is { key: string; label: string; body: any; description: string } =>
-            Boolean(val),
+            Boolean(val)
         );
 
     if (tabs.length === 0) {
@@ -208,7 +209,7 @@ function OpenAPIExample(props: {
         return <OpenAPIEmptyResponseExample />;
     }
 
-    return <context.CodeBlock code={code} syntax={syntax} />;
+    return context.renderCodeBlock({ code, syntax });
 }
 
 function stringifyExample(args: { example: OpenAPIV3.ExampleObject; xml: boolean }): string | null {
@@ -226,7 +227,7 @@ function stringifyExample(args: { example: OpenAPIV3.ExampleObject; xml: boolean
         return json2xml(example.value);
     }
 
-    return JSON.stringify(example.value, null, 2);
+    return stringifyOpenAPI(example.value, null, 2);
 }
 
 /**

package/src/OpenAPIResponses.tsx

@@ -1,9 +1,9 @@
 import type { OpenAPIV3, OpenAPIV3_1 } from '@gitbook/openapi-parser';
-import { OpenAPIResponse } from './OpenAPIResponse';
-import { OpenAPIClientContext } from './types';
 import { InteractiveSection } from './InteractiveSection';
-import { OpenAPIDisclosureGroup } from './OpenAPIDisclosureGroup';
 import { Markdown } from './Markdown';
+import { OpenAPIDisclosureGroup } from './OpenAPIDisclosureGroup';
+import { OpenAPIResponse } from './OpenAPIResponse';
+import type { OpenAPIClientContext } from './types';
 
 /**
  * Display an interactive response body.
@@ -55,7 +55,7 @@ export function OpenAPIResponses(props: {
                                 ),
                             })),
                         };
-                    },
+                    }
                 )}
             />
         </InteractiveSection>

package/src/OpenAPISchema.test.ts

@@ -1,6 +1,6 @@
-import { it, describe, expect } from 'bun:test';
-import { getSchemaAlternatives } from './OpenAPISchema';
+import { describe, expect, it } from 'bun:test';
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import { getSchemaAlternatives } from './OpenAPISchema';
 
 describe('getSchemaAlternatives', () => {
     it('should flatten oneOf', () => {
@@ -21,7 +21,7 @@ describe('getSchemaAlternatives', () => {
                         type: 'string',
                     },
                 ],
-            }),
+            })
         ).toEqual([
             [
                 {
@@ -56,7 +56,7 @@ describe('getSchemaAlternatives', () => {
                         type: 'string',
                     },
                 ],
-            }),
+            })
         ).toEqual([
             [
                 {
@@ -86,7 +86,7 @@ describe('getSchemaAlternatives', () => {
             ],
         };
 
-        a.anyOf!.push(a);
+        a.anyOf?.push(a);
 
         expect(getSchemaAlternatives(a)).toEqual([
             [