@gitbook/react-openapi 1.1.8 → 1.1.10

package/src/generateSchemaExample.ts

@@ -16,14 +16,10 @@ export function generateSchemaExample(
     schema: OpenAPIV3.SchemaObject,
     options?: GenerateSchemaExampleOptions
 ): JSONValue | undefined {
-    return getExampleFromSchema(
-        schema,
-        {
-            emptyString: 'text',
-            ...options,
-        },
-        3 // Max depth for circular references
-    );
+    return getExampleFromSchema(schema, {
+        emptyString: 'text',
+        ...options,
+    });
 }
 
 /**
@@ -103,21 +99,6 @@ function guessFromFormat(schema: Record<string, any>, fallback = '') {
     return genericExampleValues[schema.format] ?? fallback;
 }
 
-/** Map of all the results */
-const resultCache = new WeakMap<Record<string, any>, any>();
-
-/** Store result in the cache, and return the result */
-function cache(schema: Record<string, any>, result: unknown) {
-    // Avoid unnecessary WeakMap operations for primitive values
-    if (typeof result !== 'object' || result === null) {
-        return result;
-    }
-
-    resultCache.set(schema, result);
-
-    return result;
-}
-
 /**
  * This function takes an OpenAPI schema and generates an example from it
  * Forked from : https://github.com/scalar/scalar/blob/main/packages/oas-utils/src/spec-getters/getExampleFromSchema.ts
@@ -152,8 +133,20 @@ const getExampleFromSchema = (
     },
     level = 0,
     parentSchema?: Record<string, any>,
-    name?: string
+    name?: string,
+    resultCache = new WeakMap<Record<string, any>, any>()
 ): any => {
+    // Store result in the cache, and return the result
+    function cache(schema: Record<string, any>, result: unknown) {
+        // Avoid unnecessary WeakMap operations for primitive values
+        if (typeof result !== 'object' || result === null) {
+            return result;
+        }
+
+        resultCache.set(schema, result);
+        return result;
+    }
+
     // Check if the result is already cached
     if (resultCache.has(schema)) {
         return resultCache.get(schema);
@@ -173,6 +166,11 @@ const getExampleFromSchema = (
     // But if `emptyString` is  set, we do want to see some values.
     const makeUpRandomData = !!options?.emptyString;
 
+    // If the property is deprecated we don't show it in examples.
+    if (schema.deprecated) {
+        return undefined;
+    }
+
     // Check if the property is read-only/write-only
     if (
         (options?.mode === 'write' && schema.readOnly) ||
@@ -245,7 +243,8 @@ const getExampleFromSchema = (
                         options,
                         level + 1,
                         schema,
-                        propertyName
+                        propertyName,
+                        resultCache
                     );
 
                     if (typeof response[propertyXmlTagName ?? propertyName] === 'undefined') {
@@ -269,7 +268,8 @@ const getExampleFromSchema = (
                         options,
                         level + 1,
                         schema,
-                        exampleKey
+                        exampleKey,
+                        resultCache
                     );
                 }
             }
@@ -290,21 +290,51 @@ const getExampleFromSchema = (
                 response.ANY_ADDITIONAL_PROPERTY = getExampleFromSchema(
                     schema.additionalProperties,
                     options,
-                    level + 1
+                    level + 1,
+                    undefined,
+                    undefined,
+                    resultCache
                 );
             }
         }
 
         if (schema.anyOf !== undefined) {
-            Object.assign(response, getExampleFromSchema(schema.anyOf[0], options, level + 1));
+            Object.assign(
+                response,
+                getExampleFromSchema(
+                    schema.anyOf[0],
+                    options,
+                    level + 1,
+                    undefined,
+                    undefined,
+                    resultCache
+                )
+            );
         } else if (schema.oneOf !== undefined) {
-            Object.assign(response, getExampleFromSchema(schema.oneOf[0], options, level + 1));
+            Object.assign(
+                response,
+                getExampleFromSchema(
+                    schema.oneOf[0],
+                    options,
+                    level + 1,
+                    undefined,
+                    undefined,
+                    resultCache
+                )
+            );
         } else if (schema.allOf !== undefined) {
             Object.assign(
                 response,
                 ...schema.allOf
                     .map((item: Record<string, any>) =>
-                        getExampleFromSchema(item, options, level + 1, schema)
+                        getExampleFromSchema(
+                            item,
+                            options,
+                            level + 1,
+                            schema,
+                            undefined,
+                            resultCache
+                        )
                     )
                     .filter((item: any) => item !== undefined)
             );
@@ -335,7 +365,9 @@ const getExampleFromSchema = (
                         { type: 'object', allOf: schema.items.allOf },
                         options,
                         level + 1,
-                        schema
+                        schema,
+                        undefined,
+                        resultCache
                     );
 
                     return cache(
@@ -346,7 +378,14 @@ const getExampleFromSchema = (
                 // For non-objects (like strings), collect all examples
                 const examples = schema.items.allOf
                     .map((item: Record<string, any>) =>
-                        getExampleFromSchema(item, options, level + 1, schema)
+                        getExampleFromSchema(
+                            item,
+                            options,
+                            level + 1,
+                            schema,
+                            undefined,
+                            resultCache
+                        )
                     )
                     .filter((item: any) => item !== undefined);
 
@@ -368,7 +407,14 @@ const getExampleFromSchema = (
                 const schemas = schema.items[rule].slice(0, 1);
                 const exampleFromRule = schemas
                     .map((item: Record<string, any>) =>
-                        getExampleFromSchema(item, options, level + 1, schema)
+                        getExampleFromSchema(
+                            item,
+                            options,
+                            level + 1,
+                            schema,
+                            undefined,
+                            resultCache
+                        )
                     )
                     .filter((item: any) => item !== undefined);
 
@@ -380,7 +426,14 @@ const getExampleFromSchema = (
         }
 
         if (schema.items?.type) {
-            const exampleFromSchema = getExampleFromSchema(schema.items, options, level + 1);
+            const exampleFromSchema = getExampleFromSchema(
+                schema.items,
+                options,
+                level + 1,
+                undefined,
+                undefined,
+                resultCache
+            );
 
             return wrapItems ? [{ [itemsXmlTagName]: exampleFromSchema }] : [exampleFromSchema];
         }
@@ -407,7 +460,14 @@ const getExampleFromSchema = (
         const firstOneOfItem = discriminateSchema[0];
 
         // Return an example for the first item
-        return getExampleFromSchema(firstOneOfItem, options, level + 1);
+        return getExampleFromSchema(
+            firstOneOfItem,
+            options,
+            level + 1,
+            undefined,
+            undefined,
+            resultCache
+        );
     }
 
     // Check if schema has the `allOf` key
@@ -417,7 +477,14 @@ const getExampleFromSchema = (
         // Loop through all `allOf` schemas
         schema.allOf.forEach((allOfItem: Record<string, any>) => {
             // Return an example from the schema
-            const newExample = getExampleFromSchema(allOfItem, options, level + 1);
+            const newExample = getExampleFromSchema(
+                allOfItem,
+                options,
+                level + 1,
+                undefined,
+                undefined,
+                resultCache
+            );
 
             // Merge or overwrite the example
             example =

package/src/getOrCreateStoreByKey.ts

@@ -0,0 +1,35 @@
+'use client';
+
+import { createStore } from 'zustand';
+
+type Key = string | number;
+
+type State = {
+    key: Key | null;
+};
+
+type Actions = { setKey: (key: Key | null) => void };
+
+type Store = State & Actions;
+
+const createStateStore = (initial?: Key) => {
+    return createStore<Store>()((set) => ({
+        key: initial ?? null,
+        setKey: (key) => {
+            set(() => ({ key }));
+        },
+    }));
+};
+
+const defaultStores = new Map<string, ReturnType<typeof createStateStore>>();
+
+const createStateStoreFactory = (stores: typeof defaultStores) => {
+    return (storeKey: string, initialKey?: Key) => {
+        if (!stores.has(storeKey)) {
+            stores.set(storeKey, createStateStore(initialKey));
+        }
+        return stores.get(storeKey)!;
+    };
+};
+
+export const getOrCreateStoreByKey = createStateStoreFactory(defaultStores);

package/src/index.ts

@@ -2,4 +2,4 @@ export * from './schemas';
 export * from './OpenAPIOperation';
 export * from './OpenAPIOperationContext';
 export * from './resolveOpenAPIOperation';
-export type { OpenAPISchemasData, OpenAPIOperationData } from './types';
+export type { OpenAPIOperationData, OpenAPIContext } from './types';

package/src/resolveOpenAPIOperation.ts

@@ -40,16 +40,27 @@ export async function resolveOpenAPIOperation(
     }
 
     const servers = 'servers' in schema ? (schema.servers ?? []) : [];
-    const security = flattenSecurities(operation.security ?? schema.security ?? []);
+    const security: OpenAPIV3_1.SecurityRequirementObject[] =
+        operation.security ?? schema.security ?? [];
+
+    // If security includes an empty object, it means that the security is optional
+    const isOptionalSecurity = security.some((entry) => Object.keys(entry).length === 0);
+    const flatSecurities = flattenSecurities(security);
 
     // Resolve securities
     const securities: OpenAPIOperationData['securities'] = [];
-    for (const entry of security) {
+    for (const entry of flatSecurities) {
         const securityKey = Object.keys(entry)[0];
         if (securityKey) {
             const securityScheme = schema.components?.securitySchemes?.[securityKey];
             if (securityScheme && !checkIsReference(securityScheme)) {
-                securities.push([securityKey, securityScheme]);
+                securities.push([
+                    securityKey,
+                    {
+                        ...securityScheme,
+                        required: !isOptionalSecurity,
+                    },
+                ]);
             }
         }
     }

package/src/schemas/OpenAPISchemas.tsx

@@ -1,99 +1,104 @@
+import type { OpenAPISchema } from '@gitbook/openapi-parser';
 import clsx from 'clsx';
 import { OpenAPIDisclosureGroup } from '../OpenAPIDisclosureGroup';
+import { OpenAPIExample, getExampleFromSchema } from '../OpenAPIExample';
 import { OpenAPIRootSchema } from '../OpenAPISchemaServer';
-import { Section, SectionBody } from '../StaticSection';
-import type { OpenAPIClientContext, OpenAPIContextProps, OpenAPISchemasData } from '../types';
-
-type OpenAPISchemasContextProps = Omit<
-    OpenAPIContextProps,
-    'renderCodeBlock' | 'renderHeading' | 'renderDocument'
->;
+import { Section, SectionBody, StaticSection } from '../StaticSection';
+import { getOpenAPIClientContext } from '../context';
+import type { OpenAPIContext } from '../types';
 
 /**
- * Display OpenAPI Schemas.
+ * OpenAPI Schemas component.
  */
 export function OpenAPISchemas(props: {
     className?: string;
-    data: OpenAPISchemasData;
-    context: OpenAPISchemasContextProps;
+    schemas: OpenAPISchema[];
+    context: OpenAPIContext;
     /**
      * Whether to show the schema directly if there is only one.
      */
     grouped?: boolean;
 }) {
-    const { className, data, context, grouped } = props;
-    const { schemas } = data;
+    const { schemas, context, grouped, className } = props;
 
-    const clientContext: OpenAPIClientContext = {
-        defaultInteractiveOpened: context.defaultInteractiveOpened,
-        icons: context.icons,
-        blockKey: context.blockKey,
-    };
+    const firstSchema = schemas[0];
 
-    if (!schemas.length) {
+    if (!firstSchema) {
         return null;
     }
 
-    return (
-        <div className={clsx('openapi-schemas', className)}>
-            <OpenAPIRootSchemasSchema grouped={grouped} schemas={schemas} context={clientContext} />
-        </div>
-    );
-}
-
-/**
- * Root schema for OpenAPI schemas.
- * It displays a single model or a disclosure group for multiple schemas.
- */
-function OpenAPIRootSchemasSchema(props: {
-    schemas: OpenAPISchemasData['schemas'];
-    context: OpenAPIClientContext;
-    grouped?: boolean;
-}) {
-    const { schemas, context, grouped } = props;
+    const clientContext = getOpenAPIClientContext(context);
 
     // If there is only one model and we are not grouping, we show it directly.
     if (schemas.length === 1 && !grouped) {
-        const schema = schemas?.[0]?.schema;
-
-        if (!schema) {
-            return null;
-        }
-
+        const title = `The ${firstSchema.name} object`;
         return (
-            <Section>
-                <SectionBody>
-                    <OpenAPIRootSchema schema={schema} context={context} />
-                </SectionBody>
-            </Section>
+            <div className={clsx('openapi-schemas', className)}>
+                <div className="openapi-summary" id={context.id}>
+                    {context.renderHeading({
+                        title,
+                    })}
+                </div>
+                <div className="openapi-columns">
+                    <div className="openapi-column-spec">
+                        <StaticSection className="openapi-parameters" header="Attributes">
+                            <OpenAPIRootSchema
+                                schema={firstSchema.schema}
+                                context={clientContext}
+                            />
+                        </StaticSection>
+                    </div>
+                    <div className="openapi-column-preview">
+                        <div className="openapi-column-preview-body">
+                            <div className="openapi-panel">
+                                <h4 className="openapi-panel-heading">{title}</h4>
+                                <div className="openapi-panel-body">
+                                    <OpenAPIExample
+                                        example={getExampleFromSchema({
+                                            schema: firstSchema.schema,
+                                        })}
+                                        context={context}
+                                        syntax="json"
+                                    />
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
         );
     }
 
     // If there are multiple schemas, we use a disclosure group to show them all.
     return (
-        <OpenAPIDisclosureGroup
-            allowsMultipleExpanded
-            icon={context.icons.chevronRight}
-            groups={schemas.map(({ name, schema }) => ({
-                id: name,
-                label: (
-                    <div className="openapi-response-tab-content" key={`model-${name}`}>
-                        <span className="openapi-response-statuscode">{name}</span>
-                    </div>
-                ),
-                tabs: [
-                    {
-                        id: 'model',
-                        body: (
-                            <Section className="openapi-section-schemas">
-                                <SectionBody>
-                                    <OpenAPIRootSchema schema={schema} context={context} />
-                                </SectionBody>
-                            </Section>
-                        ),
-                    },
-                ],
-            }))}
-        />
+        <div className={clsx('openapi-schemas', className)}>
+            <OpenAPIDisclosureGroup
+                allowsMultipleExpanded
+                icon={context.icons.chevronRight}
+                groups={schemas.map(({ name, schema }) => ({
+                    id: name,
+                    label: (
+                        <div className="openapi-response-tab-content" key={`model-${name}`}>
+                            <span className="openapi-response-statuscode">{name}</span>
+                        </div>
+                    ),
+                    tabs: [
+                        {
+                            id: 'model',
+                            body: (
+                                <Section className="openapi-section-schemas">
+                                    <SectionBody>
+                                        <OpenAPIRootSchema
+                                            schema={schema}
+                                            context={clientContext}
+                                        />
+                                    </SectionBody>
+                                </Section>
+                            ),
+                        },
+                    ],
+                }))}
+            />
+        </div>
     );
 }

package/src/schemas/resolveOpenAPISchemas.ts

@@ -1,9 +1,6 @@
-import type { Filesystem, OpenAPIV3xDocument } from '@gitbook/openapi-parser';
+import type { Filesystem, OpenAPISchema, OpenAPIV3xDocument } from '@gitbook/openapi-parser';
 import { filterSelectedOpenAPISchemas } from '@gitbook/openapi-parser';
 import { dereferenceFilesystem } from '../dereference';
-import type { OpenAPISchemasData } from '../types';
-
-//!!TODO: We should return only the schemas that are used in the block. Still a WIP awaiting future work.
 
 /**
  * Resolve an OpenAPI schemas from a file and compile it to a more usable format.
@@ -14,7 +11,9 @@ export async function resolveOpenAPISchemas(
     options: {
         schemas: string[];
     }
-): Promise<OpenAPISchemasData | null> {
+): Promise<{
+    schemas: OpenAPISchema[];
+} | null> {
     const { schemas: selectedSchemas } = options;
 
     const schema = await dereferenceFilesystem(filesystem);

package/src/types.ts

@@ -1,33 +1,13 @@
 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;
+export interface OpenAPIClientContext {
     /**
-     * Render the document of the operation.
+     * Icons used in the block.
      */
-    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;
@@ -39,14 +19,46 @@ export interface OpenAPIClientContext {
      * @default false
      */
     defaultInteractiveOpened?: boolean;
+
     /**
      * The key of the block
      */
     blockKey?: string;
-    /** Optional id attached to the OpenAPI Operation heading and used as an anchor */
+
+    /**
+     * Optional id attached to the heading and used as an anchor.
+     */
     id?: string;
 }
 
+export interface OpenAPIContext 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;
+
+    /**
+     * Specification URL.
+     */
+    specUrl: string;
+}
+
+export type OpenAPISecurityWithRequired = OpenAPIV3.SecuritySchemeObject & { required?: boolean };
+
 export interface OpenAPIOperationData extends OpenAPICustomSpecProperties {
     path: string;
     method: string;
@@ -58,10 +70,5 @@ export interface OpenAPIOperationData extends OpenAPICustomSpecProperties {
     operation: OpenAPIV3.OperationObject<OpenAPICustomOperationProperties>;
 
     /** Securities that should be used for this operation */
-    securities: [string, OpenAPIV3.SecuritySchemeObject][];
-}
-
-export interface OpenAPISchemasData {
-    /** Components schemas to be used for schemas */
-    schemas: OpenAPISchema[];
+    securities: [string, OpenAPISecurityWithRequired][];
 }

package/dist/useSyncedTabsGlobalState.d.ts

@@ -1,10 +0,0 @@
-type Key = string | number;
-type TabState = {
-    tabKey: Key | null;
-};
-type TabActions = {
-    setTabKey: (tab: Key | null) => void;
-};
-type TabStore = TabState & TabActions;
-export declare const getOrCreateTabStoreByKey: (storeKey: string, initialKey?: Key) => import("zustand").StoreApi<TabStore>;
-export {};

package/dist/useSyncedTabsGlobalState.js

@@ -1,20 +0,0 @@
-'use client';
-import { createStore } from 'zustand';
-var createTabStore = function (initialTab) {
-    return createStore()(function (set) { return ({
-        tabKey: initialTab !== null && initialTab !== void 0 ? initialTab : null,
-        setTabKey: function (tabKey) {
-            set(function () { return ({ tabKey: tabKey }); });
-        },
-    }); });
-};
-var defaultTabStores = new Map();
-var createTabStoreFactory = function (stores) {
-    return function (storeKey, initialKey) {
-        if (!stores.has(storeKey)) {
-            stores.set(storeKey, createTabStore(initialKey));
-        }
-        return stores.get(storeKey);
-    };
-};
-export var getOrCreateTabStoreByKey = createTabStoreFactory(defaultTabStores);

package/src/useSyncedTabsGlobalState.ts

@@ -1,35 +0,0 @@
-'use client';
-
-import { createStore } from 'zustand';
-
-type Key = string | number;
-
-type TabState = {
-    tabKey: Key | null;
-};
-
-type TabActions = { setTabKey: (tab: Key | null) => void };
-
-type TabStore = TabState & TabActions;
-
-const createTabStore = (initialTab?: Key) => {
-    return createStore<TabStore>()((set) => ({
-        tabKey: initialTab ?? null,
-        setTabKey: (tabKey) => {
-            set(() => ({ tabKey }));
-        },
-    }));
-};
-
-const defaultTabStores = new Map<string, ReturnType<typeof createTabStore>>();
-
-const createTabStoreFactory = (stores: typeof defaultTabStores) => {
-    return (storeKey: string, initialKey?: Key) => {
-        if (!stores.has(storeKey)) {
-            stores.set(storeKey, createTabStore(initialKey));
-        }
-        return stores.get(storeKey)!;
-    };
-};
-
-export const getOrCreateTabStoreByKey = createTabStoreFactory(defaultTabStores);