wip

nolannbiron · nolannbiron · commit d7200df71993 · 2025-03-06T18:23:59.000+01:00
diff --git a/packages/gitbook/src/components/DocumentView/OpenAPI/style.css b/packages/gitbook/src/components/DocumentView/OpenAPI/style.css
@@ -619,3 +619,15 @@
 .openapi-section-body.openapi-schema.openapi-schema-root {
     @apply space-y-2.5;
 }
+
+.openapi-models-properties {
+    @apply border border-tint-subtle rounded-lg;
+}
+
+.openapi-models-properties .openapi-schema-body {
+    @apply p-2.5;
+}
+
+.openapi-models .openapi-disclosure-group-panel > .openapi-section > .openapi-schema-body {
+    @apply py-0;
+}
diff --git a/packages/gitbook/src/lib/openapi/fetch.ts b/packages/gitbook/src/lib/openapi/fetch.ts
@@ -1,6 +1,11 @@
 import type { DocumentBlockOpenAPI, DocumentBlockOpenAPIOperation } from '@gitbook/api';
 import { OpenAPIParseError, parseOpenAPI } from '@gitbook/openapi-parser';
-import { type OpenAPIOperationData, resolveOpenAPIOperation } from '@gitbook/react-openapi';
+import {
+    type OpenAPIModelsData,
+    type OpenAPIOperationData,
+    resolveOpenAPIModels,
+    resolveOpenAPIOperation,
+} from '@gitbook/react-openapi';
 import type { GitBookAnyContext } from '@v2/lib/context';
 
 import { type CacheFunctionOptions, cache, noCacheFetchOptions } from '@/lib/cache';
@@ -12,47 +17,71 @@ import { enrichFilesystem } from './enrich';
 
 export type AnyOpenAPIOperationBlock = DocumentBlockOpenAPI | DocumentBlockOpenAPIOperation;
 
+export type OpenAPIBlockType = 'operation' | 'models';
+
+export type ResolveOpenAPIOperationBlockResult = {
+    error: undefined;
+    data: OpenAPIOperationData | null;
+    specUrl: string | null;
+};
+
+export type ResolveOpenAPIModelsBlockResult = {
+    error: undefined;
+    data: OpenAPIModelsData | null;
+    specUrl: string | null;
+};
+
+export type ResolveOpenAPIBlockResult<T extends OpenAPIBlockType = OpenAPIBlockType> =
+    | (T extends 'operation' ? ResolveOpenAPIOperationBlockResult : ResolveOpenAPIModelsBlockResult)
+    | ResolveOpenAPIBlockError;
+
+type ResolveOpenAPIBlockError = { error: OpenAPIParseError; data?: undefined; specUrl?: undefined };
+
+type ResolveOpenAPIBlockArgs<T extends OpenAPIBlockType = OpenAPIBlockType> = {
+    block: AnyOpenAPIOperationBlock;
+    context: GitBookAnyContext;
+    /**
+     * The type of the block.
+     * Can be either 'operation' or 'models'.
+     * @default 'operation'
+     */
+    type?: T | OpenAPIBlockType;
+};
+
 const weakmap = new WeakMap<AnyOpenAPIOperationBlock, Promise<ResolveOpenAPIBlockResult>>();
 
 /**
  * Cache the result of resolving an OpenAPI block.
  * It is important because the resolve is called in sections and in the block itself.
  */
-export function resolveOpenAPIBlock(
-    args: ResolveOpenAPIBlockArgs
-): Promise<ResolveOpenAPIBlockResult> {
-    if (weakmap.has(args.block)) {
-        return weakmap.get(args.block)!;
-    }
+export function resolveOpenAPIBlock<T extends OpenAPIBlockType = 'operation'>(
+    args: ResolveOpenAPIBlockArgs<T>
+): Promise<ResolveOpenAPIBlockResult<T>> {
+    // if (weakmap.has(args.block)) {
+    //     return weakmap.get(args.block) as Promise<ResolveOpenAPIBlockResult<T>>;
+    // }
 
     const result = baseResolveOpenAPIBlock(args);
-    weakmap.set(args.block, result);
+    weakmap.set(args.block, result as Promise<ResolveOpenAPIBlockResult<T>>);
     return result;
 }
 
-type ResolveOpenAPIBlockArgs = {
-    block: AnyOpenAPIOperationBlock;
-    context: GitBookAnyContext;
-};
-export type ResolveOpenAPIBlockResult =
-    | { error?: undefined; data: OpenAPIOperationData | null; specUrl: string | null }
-    | { error: OpenAPIParseError; data?: undefined; specUrl?: undefined };
 /**
  * Resolve OpenAPI block.
  */
-async function baseResolveOpenAPIBlock(
-    args: ResolveOpenAPIBlockArgs
-): Promise<ResolveOpenAPIBlockResult> {
-    const { context, block } = args;
+async function baseResolveOpenAPIBlock<T extends OpenAPIBlockType = 'operation'>(
+    args: ResolveOpenAPIBlockArgs<T>
+): Promise<ResolveOpenAPIBlockResult<T>> {
+    const { context, block, type = 'operation' } = args;
     if (!block.data.path || !block.data.method) {
-        return { data: null, specUrl: null };
+        return { data: null, specUrl: null } as ResolveOpenAPIBlockResult<T>;
     }
 
     const ref = block.data.ref;
     const resolved = ref ? await resolveContentRef(ref, context) : null;
 
     if (!resolved) {
-        return { data: null, specUrl: null };
+        return { data: null, specUrl: null } as ResolveOpenAPIBlockResult<T>;
     }
 
     try {
@@ -64,12 +93,17 @@ async function baseResolveOpenAPIBlock(
             return fetchFilesystem(resolved.href);
         })();
 
+        if (type === 'models') {
+            const data = await resolveOpenAPIModels(filesystem);
+            return { data: data, specUrl: resolved.href } as ResolveOpenAPIBlockResult<T>;
+        }
+
         const data = await resolveOpenAPIOperation(filesystem, {
             path: block.data.path,
             method: block.data.method,
         });
 
-        return { data, specUrl: resolved.href };
+        return { data, specUrl: resolved.href } as ResolveOpenAPIBlockResult<T>;
     } catch (error) {
         if (error instanceof OpenAPIParseError) {
             return { error };
diff --git a/packages/react-openapi/src/OpenAPISchema.tsx b/packages/react-openapi/src/OpenAPISchema.tsx
@@ -166,7 +166,7 @@ function OpenAPISchemaAlternative(props: {
 /**
  * Render a circular reference to a schema.
  */
-function OpenAPISchemaCircularRef(props: { id: string; schema: OpenAPIV3.SchemaObject }) {
+export function OpenAPISchemaCircularRef(props: { id: string; schema: OpenAPIV3.SchemaObject }) {
     const { id, schema } = props;
 
     return (
@@ -198,12 +198,9 @@ export function OpenAPISchemaEnum(props: { enumValues: any[] }) {
     );
 }
 
-export function OpenAPISchemaPresentation(
-    props: { property: OpenAPISchemaPropertyEntry } & { showType?: boolean }
-) {
+export function OpenAPISchemaPresentation(props: { property: OpenAPISchemaPropertyEntry }) {
     const {
         property: { schema, propertyName, required },
-        showType = true,
     } = props;
 
     const description = resolveDescription(schema);
@@ -213,7 +210,7 @@ export function OpenAPISchemaPresentation(
         <div className="openapi-schema-presentation">
             <OpenAPISchemaName
                 schema={schema}
-                type={showType ? getSchemaTitle(schema) : undefined}
+                type={getSchemaTitle(schema)}
                 propertyName={propertyName}
                 required={required}
             />
diff --git a/packages/react-openapi/src/index.ts b/packages/react-openapi/src/index.ts
@@ -1,5 +1,5 @@
 export * from './models';
 export * from './OpenAPIOperation';
 export * from './OpenAPIOperationContext';
-export * from './resolveOpenAPIOperation';
-export type { OpenAPIOperationData } from './types';
+export { resolveOpenAPIOperation } from './resolveOpenAPIOperation';
+export type { OpenAPIModelsData, OpenAPIOperationData } from './types';
diff --git a/packages/react-openapi/src/models/OpenAPIModelSchema.tsx b/packages/react-openapi/src/models/OpenAPIModelSchema.tsx
@@ -1,3 +1,96 @@
-export function OpenAPIModelSchema() {
-    return <></>;
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import clsx from 'clsx';
+import { useId } from 'react';
+import { InteractiveSection } from '../InteractiveSection';
+import {
+    OpenAPISchemaAlternativesItem,
+    OpenAPISchemaCircularRef,
+    OpenAPISchemaProperties,
+    OpenAPISchemaProperty,
+    type OpenAPISchemaPropertyEntry,
+    getSchemaAlternatives,
+    getSchemaProperties,
+} from '../OpenAPISchema';
+import type { OpenAPIClientContext } from '../types';
+
+type CircularRefsIds = Map<OpenAPIV3.SchemaObject, string>;
+
+export function OpenAPIModelSchema(
+    props: OpenAPISchemaPropertyEntry & {
+        /** Set of objects already observed as parents */
+        circularRefs?: CircularRefsIds;
+        context: OpenAPIClientContext;
+        className?: string;
+    }
+) {
+    const {
+        schema,
+        circularRefs: parentCircularRefs = new Map<OpenAPIV3.SchemaObject, string>(),
+        context,
+        className,
+    } = props;
+
+    const id = useId();
+
+    const parentCircularRef = parentCircularRefs.get(schema);
+    const circularRefs = new Map(parentCircularRefs).set(schema, id);
+
+    // Avoid recursing infinitely, and instead render a link to the parent schema
+    const properties = parentCircularRef ? null : getSchemaProperties(schema);
+    const alternatives = parentCircularRef
+        ? null
+        : getSchemaAlternatives(schema, new Set(circularRefs.keys()));
+
+    if (alternatives?.[0].length) {
+        return (
+            <OpenAPISchemaAlternativesItem
+                schema={schema}
+                circularRefs={circularRefs}
+                context={context}
+                alternatives={alternatives}
+            />
+        );
+    }
+
+    if ((properties && properties.length > 0) || schema.type === 'object') {
+        return (
+            <InteractiveSection id={id} className={clsx('openapi-schema', className)}>
+                {properties && properties.length > 0 ? (
+                    <div className="openapi-models-properties">
+                        <OpenAPISchemaProperties
+                            properties={properties}
+                            circularRefs={circularRefs}
+                            context={context}
+                        />
+                    </div>
+                ) : null}
+                {parentCircularRef ? (
+                    <OpenAPISchemaCircularRef id={parentCircularRef} schema={schema} />
+                ) : null}
+            </InteractiveSection>
+        );
+    }
+
+    return (
+        <InteractiveSection id={id} className={clsx('openapi-schema', className)}>
+            {(properties && properties.length > 0) ||
+            (schema.enum && schema.enum.length > 0) ||
+            parentCircularRef ? (
+                <div className="openapi-models-properties">
+                    {properties?.length ? (
+                        <OpenAPISchemaProperties
+                            properties={properties}
+                            circularRefs={circularRefs}
+                            context={context}
+                        />
+                    ) : (
+                        <OpenAPISchemaProperty schema={schema} context={context} />
+                    )}
+                    {parentCircularRef ? (
+                        <OpenAPISchemaCircularRef id={parentCircularRef} schema={schema} />
+                    ) : null}
+                </div>
+            ) : null}
+        </InteractiveSection>
+    );
 }
diff --git a/packages/react-openapi/src/models/OpenAPIModels.tsx b/packages/react-openapi/src/models/OpenAPIModels.tsx
@@ -1,19 +1,19 @@
 import clsx from 'clsx';
 
 import { OpenAPIDisclosureGroup } from '../OpenAPIDisclosureGroup';
-import { OpenAPISchemaProperty } from '../OpenAPISchema';
-import type { OpenAPIClientContext, OpenAPIContextProps, OpenAPIOperationData } from '../types';
+import type { OpenAPIClientContext, OpenAPIContextProps, OpenAPIModelsData } from '../types';
+import { OpenAPIModelSchema } from './OpenAPIModelSchema';
 
 /**
  * Display OpenAPI Models.
  */
 export function OpenAPIModels(props: {
     className?: string;
-    data: OpenAPIOperationData;
+    data: OpenAPIModelsData;
     context: OpenAPIContextProps;
 }) {
     const { className, data, context } = props;
-    const { components } = data;
+    const { models } = data;
 
     const clientContext: OpenAPIClientContext = {
         defaultInteractiveOpened: context.defaultInteractiveOpened,
@@ -23,18 +23,18 @@ export function OpenAPIModels(props: {
 
     return (
         <div className={clsx('openapi-models', className)}>
-            {components.length ? (
+            {models.length ? (
                 <OpenAPIDisclosureGroup
                     allowsMultipleExpanded
                     icon={context.icons.chevronRight}
-                    groups={components.map(([name, schema]) => ({
+                    groups={models.map(([name, schema]) => ({
                         id: name,
                         label: (
                             <div className="openapi-response-tab-content" key={`model-${name}`}>
                                 <span className="openapi-response-statuscode">{name}</span>
                             </div>
                         ),
-                        body: <OpenAPISchemaProperty schema={schema} context={clientContext} />,
+                        body: <OpenAPIModelSchema schema={schema} context={clientContext} />,
                     }))}
                 />
             ) : null}
diff --git a/packages/react-openapi/src/models/index.ts b/packages/react-openapi/src/models/index.ts
@@ -1 +1,2 @@
 export { OpenAPIModels } from './OpenAPIModels';
+export * from './resolveOpenAPIModels';
diff --git a/packages/react-openapi/src/models/resolveOpenAPIModels.ts b/packages/react-openapi/src/models/resolveOpenAPIModels.ts
@@ -0,0 +1,52 @@
+import { fromJSON, toJSON } from 'flatted';
+
+import {
+    type Filesystem,
+    type OpenAPIV3,
+    type OpenAPIV3_1,
+    type OpenAPIV3xDocument,
+    shouldIgnoreEntity,
+} from '@gitbook/openapi-parser';
+import { memoDereferenceFilesystem } from '../resolveOpenAPIOperation';
+import type { OpenAPIModelsData } from '../types';
+
+export { fromJSON, toJSON };
+
+/**
+ * Resolve an OpenAPI models from a file and compile it to a more usable format.
+ * Models are extracted from the OpenAPI components.schemas
+ */
+export async function resolveOpenAPIModels(
+    filesystem: Filesystem<OpenAPIV3xDocument>
+    // operationDescriptor: {
+    //     path: string;
+    //     method: string;
+    // }
+): Promise<OpenAPIModelsData | null> {
+    // const { path, method } = operationDescriptor;
+    const schema = await memoDereferenceFilesystem(filesystem);
+
+    if (
+        !schema.components ||
+        !schema.components.schemas ||
+        !Object.keys(schema.components.schemas).length
+    ) {
+        return null;
+    }
+
+    let models: OpenAPIModelsData['models'] = [];
+
+    models = getOpenAPIComponents(schema);
+
+    return { models };
+}
+
+/**
+ * Get OpenAPI components.schemas that are not ignored.
+ */
+function getOpenAPIComponents(
+    schema: OpenAPIV3.Document | OpenAPIV3_1.Document
+): [string, OpenAPIV3.SchemaObject][] {
+    const schemas = schema.components?.schemas ?? {};
+    return Object.entries(schemas).filter(([, schema]) => !shouldIgnoreEntity(schema));
+}
diff --git a/packages/react-openapi/src/resolveOpenAPIOperation.ts b/packages/react-openapi/src/resolveOpenAPIOperation.ts
diff --git a/packages/react-openapi/src/types.ts b/packages/react-openapi/src/types.ts

Original file line number	Diff line number	Diff line change
`@@ -1 +1,2 @@`
`1`	`1`	`export { OpenAPIModels } from './OpenAPIModels';`
	`2`	`+export * from './resolveOpenAPIModels';`