@gitbook/react-openapi 1.1.9 → 1.2.0

package/dist/types.d.ts

@@ -1,47 +1,7 @@
-import type { OpenAPICustomOperationProperties, OpenAPICustomSpecProperties, OpenAPISchema, OpenAPIV3 } from '@gitbook/openapi-parser';
-export interface OpenAPIContextProps extends OpenAPIClientContext {
-    /**
-     * Render a code block.
-     */
-    renderCodeBlock: (props: {
-        code: string;
-        syntax: string;
-    }) => React.ReactNode;
-    /**
-     * Render the heading of the operation.
-     */
-    renderHeading: (props: {
-        deprecated: boolean;
-        title: string;
-        stability?: string;
-    }) => React.ReactNode;
-    /**
-     * Render the document of the operation.
-     */
-    renderDocument: (props: {
-        document: object;
-    }) => React.ReactNode;
-    /** Spec url for the Scalar Api Client */
-    specUrl: string;
-}
-export interface OpenAPIClientContext {
-    icons: {
-        chevronDown: React.ReactNode;
-        chevronRight: React.ReactNode;
-        plus: React.ReactNode;
-    };
-    /**
-     * Force all sections to be opened by default.
-     * @default false
-     */
-    defaultInteractiveOpened?: boolean;
-    /**
-     * The key of the block
-     */
-    blockKey?: string;
-    /** Optional id attached to the OpenAPI Operation heading and used as an anchor */
-    id?: string;
-}
+import type { OpenAPICustomOperationProperties, OpenAPICustomSpecProperties, OpenAPIV3 } from '@gitbook/openapi-parser';
+export type OpenAPISecurityWithRequired = OpenAPIV3.SecuritySchemeObject & {
+    required?: boolean;
+};
 export interface OpenAPIOperationData extends OpenAPICustomSpecProperties {
     path: string;
     method: string;
@@ -50,9 +10,13 @@ export interface OpenAPIOperationData extends OpenAPICustomSpecProperties {
     /** Spec of the operation */
     operation: OpenAPIV3.OperationObject<OpenAPICustomOperationProperties>;
     /** Securities that should be used for this operation */
-    securities: [string, OpenAPIV3.SecuritySchemeObject][];
+    securities: [string, OpenAPISecurityWithRequired][];
 }
-export interface OpenAPISchemasData {
-    /** Components schemas to be used for schemas */
-    schemas: OpenAPISchema[];
+export interface OpenAPIWebhookData extends OpenAPICustomSpecProperties {
+    name: string;
+    method: string;
+    /** Servers to be used for this operation */
+    servers: OpenAPIV3.ServerObject[];
+    /** Spec of the webhook */
+    operation: OpenAPIV3.OperationObject<OpenAPICustomOperationProperties>;
 }

package/dist/util/example.d.ts

@@ -0,0 +1,35 @@
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import type { OpenAPIContext } from '../context';
+/**
+ * Generate an example from a reference object.
+ */
+export declare function getExampleFromReference(ref: OpenAPIV3.ReferenceObject, context: OpenAPIContext): OpenAPIV3.ExampleObject;
+/**
+ * Get examples from a media type object.
+ */
+export declare function getExamplesFromMediaTypeObject(args: {
+    mediaType: string;
+    mediaTypeObject: OpenAPIV3.MediaTypeObject;
+    context: OpenAPIContext;
+}): {
+    key: string;
+    example: OpenAPIV3.ExampleObject;
+}[];
+/**
+ * Get example from a schema object.
+ */
+export declare function getExampleFromSchema(args: {
+    schema: OpenAPIV3.SchemaObject;
+}): OpenAPIV3.ExampleObject;
+/**
+ * Get the examples from a media type object.
+ */
+export declare function getExamples(props: {
+    mediaTypeObject: OpenAPIV3.MediaTypeObject;
+    mediaType: string;
+    context: OpenAPIContext;
+}): {
+    key: string;
+    label: string;
+    body: import("react").JSX.Element;
+}[];

package/dist/util/example.jsx

@@ -0,0 +1,103 @@
+import { OpenAPIExample } from '../OpenAPIExample';
+import { generateSchemaExample } from '../generateSchemaExample';
+import { tString } from '../translate';
+import { checkIsReference } from '../utils';
+/**
+ * Generate an example from a reference object.
+ */
+export function getExampleFromReference(ref, context) {
+    return {
+        summary: tString(context.translation, 'unresolved_reference'),
+        value: { $ref: ref.$ref },
+    };
+}
+/**
+ * Get examples from a media type object.
+ */
+export function getExamplesFromMediaTypeObject(args) {
+    var _a;
+    var _b, _c;
+    var mediaTypeObject = args.mediaTypeObject, mediaType = args.mediaType, context = args.context;
+    if (mediaTypeObject.examples) {
+        return Object.entries(mediaTypeObject.examples).map(function (_a) {
+            var key = _a[0], example = _a[1];
+            return {
+                key: key,
+                example: checkIsReference(example)
+                    ? getExampleFromReference(example, context)
+                    : 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
+            var root = (_c = (_b = mediaTypeObject.schema.xml) === null || _b === void 0 ? void 0 : _b.name) !== null && _c !== void 0 ? _c : 'object';
+            return [
+                {
+                    key: 'default',
+                    example: {
+                        value: (_a = {},
+                            _a[root] = generateSchemaExample(mediaTypeObject.schema, {
+                                xml: mediaType === 'application/xml',
+                                mode: 'read',
+                            }),
+                            _a),
+                    },
+                },
+            ];
+        }
+        return [
+            {
+                key: 'default',
+                example: {
+                    value: generateSchemaExample(mediaTypeObject.schema, {
+                        mode: 'read',
+                    }),
+                },
+            },
+        ];
+    }
+    return [];
+}
+/**
+ * Get example from a schema object.
+ */
+export function getExampleFromSchema(args) {
+    var schema = args.schema;
+    if (schema.example) {
+        return { value: schema.example };
+    }
+    return { value: generateSchemaExample(schema, { mode: 'read' }) };
+}
+/**
+ * Get the examples from a media type object.
+ */
+export function getExamples(props) {
+    var mediaTypeObject = props.mediaTypeObject, mediaType = props.mediaType, context = props.context;
+    var examples = getExamplesFromMediaTypeObject({ mediaTypeObject: mediaTypeObject, mediaType: mediaType, context: context });
+    var syntax = getSyntaxFromMediaType(mediaType);
+    return examples.map(function (example) {
+        return {
+            key: example.key,
+            label: example.example.summary || example.key,
+            body: (<OpenAPIExample example={example.example} context={props.context} syntax={syntax}/>),
+        };
+    });
+}
+/**
+ * Get the syntax from a media type.
+ */
+function getSyntaxFromMediaType(mediaType) {
+    if (mediaType.includes('json')) {
+        return 'json';
+    }
+    if (mediaType === 'application/xml') {
+        return 'xml';
+    }
+    return 'text';
+}

package/dist/utils.d.ts

@@ -1,4 +1,5 @@
 import type { AnyObject, OpenAPIV3, OpenAPIV3_1 } from '@gitbook/openapi-parser';
+import type { OpenAPIUniversalContext } from './context';
 export declare function checkIsReference(input: unknown): input is OpenAPIV3.ReferenceObject;
 export declare function createStateKey(key: string, scope?: string): string;
 /**
@@ -29,3 +30,20 @@ export declare function parameterToProperty(parameter: OpenAPIV3.ParameterObject
     schema: OpenAPIV3.SchemaObject;
     required: boolean | undefined;
 };
+/**
+ * Get the class name for a status code.
+ * 1xx: informational
+ * 2xx: success
+ * 3xx: redirect
+ * 4xx, 5xx: error
+ */
+export declare function getStatusCodeClassName(statusCode: number | string): string;
+/**
+ * Get a default label for a status code.
+ * This is used when there is no label provided in the OpenAPI spec.
+ * 1xx: Information
+ * 2xx: Success
+ * 3xx: Redirect
+ * 4xx, 5xx: Error
+ */
+export declare function getStatusCodeDefaultLabel(statusCode: number | string, context: OpenAPIUniversalContext): string;

package/dist/utils.js

@@ -10,6 +10,7 @@ var __assign = (this && this.__assign) || function () {
     return __assign.apply(this, arguments);
 };
 import { stringifyOpenAPI } from './stringifyOpenAPI';
+import { tString } from './translate';
 export function checkIsReference(input) {
     return typeof input === 'object' && !!input && '$ref' in input;
 }
@@ -127,3 +128,59 @@ function shouldDisplayExample(schema) {
             schema.example !== null &&
             Object.keys(schema.example).length > 0));
 }
+/**
+ * Get the class name for a status code.
+ * 1xx: informational
+ * 2xx: success
+ * 3xx: redirect
+ * 4xx, 5xx: error
+ */
+export function getStatusCodeClassName(statusCode) {
+    var category = getStatusCodeCategory(statusCode);
+    switch (category) {
+        case 1:
+            return 'informational';
+        case 2:
+            return 'success';
+        case 3:
+            return 'redirect';
+        case 4:
+        case 5:
+            return 'error';
+        default:
+            return 'unknown';
+    }
+}
+/**
+ * Get a default label for a status code.
+ * This is used when there is no label provided in the OpenAPI spec.
+ * 1xx: Information
+ * 2xx: Success
+ * 3xx: Redirect
+ * 4xx, 5xx: Error
+ */
+export function getStatusCodeDefaultLabel(statusCode, context) {
+    var category = getStatusCodeCategory(statusCode);
+    switch (category) {
+        case 1:
+            return tString(context.translation, 'information');
+        case 2:
+            return tString(context.translation, 'success');
+        case 3:
+            return tString(context.translation, 'redirect');
+        case 4:
+        case 5:
+            return tString(context.translation, 'error');
+        default:
+            return '';
+    }
+}
+function getStatusCodeCategory(statusCode) {
+    var code = typeof statusCode === 'string' ? Number.parseInt(statusCode, 10) : statusCode;
+    if (Number.isNaN(code) || code < 100 || code >= 600) {
+        return 'unknown';
+    }
+    // Determine the category of the status code based on the first digit
+    var category = Math.floor(code / 100);
+    return category;
+}

package/package.json

@@ -8,12 +8,12 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "1.1.9",
+    "version": "1.2.0",
     "sideEffects": false,
     "dependencies": {
         "@gitbook/openapi-parser": "workspace:*",
-        "@scalar/api-client-react": "^1.2.5",
-        "@scalar/oas-utils": "^0.2.120",
+        "@scalar/api-client-react": "^1.2.19",
+        "@scalar/oas-utils": "^0.2.130",
         "clsx": "^2.1.1",
         "flatted": "^3.2.9",
         "json-xml-parse": "^1.3.0",

package/src/InteractiveSection.tsx

@@ -1,9 +1,10 @@
 'use client';
 
 import clsx from 'clsx';
-import { useRef, useState } from 'react';
+import { useRef } from 'react';
 import { mergeProps, useButton, useDisclosure, useFocusRing } from 'react-aria';
 import { useDisclosureState } from 'react-stately';
+import { OpenAPISelect, OpenAPISelectItem, useSelectState } from './OpenAPISelect';
 import { Section, SectionBody, SectionHeader, SectionHeaderContent } from './StaticSection';
 
 interface InteractiveSectionTab {
@@ -34,6 +35,10 @@ export function InteractiveSection(props: {
     header?: React.ReactNode;
     /** Children to display within the container */
     overlay?: React.ReactNode;
+    /** State key to use with a store */
+    stateKey?: string;
+    /** Icon for the tabs select */
+    selectIcon?: React.ReactNode;
 }) {
     const {
         id,
@@ -45,12 +50,9 @@ export function InteractiveSection(props: {
         header,
         overlay,
         toggleIcon = '▶',
+        selectIcon,
+        stateKey = 'interactive-section',
     } = props;
-
-    const [selectedTabKey, setSelectedTab] = useState(defaultTab);
-    const selectedTab: InteractiveSectionTab | undefined =
-        tabs.find((tab) => tab.key === selectedTabKey) ?? tabs[0];
-
     const state = useDisclosureState({
         defaultExpanded: defaultOpened,
     });
@@ -59,6 +61,10 @@ export function InteractiveSection(props: {
     const { buttonProps: triggerProps, panelProps } = useDisclosure({}, state, panelRef);
     const { buttonProps } = useButton(triggerProps, triggerRef);
     const { isFocusVisible, focusProps } = useFocusRing();
+    const store = useSelectState(stateKey, defaultTab);
+
+    const selectedTab: InteractiveSectionTab | undefined =
+        tabs.find((tab) => tab.key === store.key) ?? tabs[0];
 
     return (
         <Section
@@ -96,6 +102,7 @@ export function InteractiveSection(props: {
                         ) : null}
                         {header}
                     </SectionHeaderContent>
+                    {/* biome-ignore lint/a11y/useKeyWithClickEvents: we prevent default here */}
                     <div
                         className={clsx(
                             'openapi-section-header-controls',
@@ -106,24 +113,21 @@ export function InteractiveSection(props: {
                         }}
                     >
                         {tabs.length > 1 ? (
-                            <select
-                                className={clsx(
-                                    'openapi-section-select',
-                                    'openapi-select',
-                                    `${className}-tabs-select`
-                                )}
-                                value={selectedTab?.key ?? ''}
-                                onChange={(event) => {
-                                    setSelectedTab(event.target.value);
+                            <OpenAPISelect
+                                stateKey={stateKey}
+                                items={tabs}
+                                onSelectionChange={() => {
                                     state.expand();
                                 }}
+                                icon={selectIcon}
+                                placement="bottom end"
                             >
                                 {tabs.map((tab) => (
-                                    <option key={tab.key} value={tab.key}>
+                                    <OpenAPISelectItem key={tab.key} id={tab.key} value={tab}>
                                         {tab.label}
-                                    </option>
+                                    </OpenAPISelectItem>
                                 ))}
-                            </select>
+                            </OpenAPISelect>
                         ) : null}
                     </div>
                 </SectionHeader>

package/src/OpenAPICodeSample.tsx

@@ -3,15 +3,15 @@ import {
     OpenAPIMediaTypeExamplesBody,
     OpenAPIMediaTypeExamplesSelector,
 } from './OpenAPICodeSampleInteractive';
-import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
+import { OpenAPICodeSampleBody } from './OpenAPICodeSampleSelector';
 import { ScalarApiButton } from './ScalarApiButton';
-import { StaticSection } from './StaticSection';
 import { type CodeSampleGenerator, codeSampleGenerators } from './code-samples';
+import { type OpenAPIContext, getOpenAPIClientContext } from './context';
 import { generateMediaTypeExamples, generateSchemaExample } from './generateSchemaExample';
 import { stringifyOpenAPI } from './stringifyOpenAPI';
-import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
+import type { OpenAPIOperationData } from './types';
 import { getDefaultServerURL } from './util/server';
-import { checkIsReference, createStateKey } from './utils';
+import { checkIsReference } from './utils';
 
 const CUSTOM_CODE_SAMPLES_KEYS = ['x-custom-examples', 'x-code-samples', 'x-codeSamples'] as const;
 
@@ -21,9 +21,9 @@ const CUSTOM_CODE_SAMPLES_KEYS = ['x-custom-examples', 'x-code-samples', 'x-code
  */
 export function OpenAPICodeSample(props: {
     data: OpenAPIOperationData;
-    context: OpenAPIContextProps;
+    context: OpenAPIContext;
 }) {
-    const { data } = props;
+    const { data, context } = props;
 
     // If code samples are disabled at operation level, we don't display the code samples.
     if (data.operation['x-codeSamples'] === false) {
@@ -45,11 +45,12 @@ export function OpenAPICodeSample(props: {
     }
 
     return (
-        <OpenAPITabs stateKey={createStateKey('codesample')} items={samples}>
-            <StaticSection header={<OpenAPITabsList />} className="openapi-codesample">
-                <OpenAPITabsPanels />
-            </StaticSection>
-        </OpenAPITabs>
+        <OpenAPICodeSampleBody
+            context={getOpenAPIClientContext(context)}
+            data={data}
+            items={samples}
+            selectIcon={context.icons.chevronDown}
+        />
     );
 }
 
@@ -58,7 +59,7 @@ export function OpenAPICodeSample(props: {
  */
 function generateCodeSamples(props: {
     data: OpenAPIOperationData;
-    context: OpenAPIContextProps;
+    context: OpenAPIContext;
 }) {
     const { data, context } = props;
 
@@ -153,6 +154,7 @@ function generateCodeSamples(props: {
                         method={data.method}
                         path={data.path}
                         renderers={renderers}
+                        blockKey={context.blockKey}
                     />
                 ),
                 footer: (
@@ -189,7 +191,7 @@ export interface MediaTypeRenderer {
 function OpenAPICodeSampleFooter(props: {
     data: OpenAPIOperationData;
     renderers: MediaTypeRenderer[];
-    context: OpenAPIContextProps;
+    context: OpenAPIContext;
 }) {
     const { data, context, renderers } = props;
     const { method, path } = data;
@@ -213,11 +215,20 @@ function OpenAPICodeSampleFooter(props: {
                     method={data.method}
                     path={data.path}
                     renderers={renderers}
+                    selectIcon={context.icons.chevronDown}
+                    blockKey={context.blockKey}
                 />
             ) : (
                 <span />
             )}
-            {!hideTryItPanel && <ScalarApiButton method={method} path={path} specUrl={specUrl} />}
+            {!hideTryItPanel && (
+                <ScalarApiButton
+                    context={getOpenAPIClientContext(context)}
+                    method={method}
+                    path={path}
+                    specUrl={specUrl}
+                />
+            )}
         </div>
     );
 }
@@ -227,7 +238,7 @@ function OpenAPICodeSampleFooter(props: {
  */
 function getCustomCodeSamples(props: {
     data: OpenAPIOperationData;
-    context: OpenAPIContextProps;
+    context: OpenAPIContext;
 }) {
     const { data, context } = props;