@gitbook/react-openapi 1.1.9 → 1.1.10

package/src/generateSchemaExample.ts

@@ -166,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) ||

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);