Implement OpenAPI models blocks (#2908)

Author: nolannbiron

.changeset/good-dogs-shave.md

@@ -0,0 +1,7 @@
+---
+'@gitbook/openapi-parser': minor
+'@gitbook/react-openapi': minor
+'gitbook': minor
+---
+
+Implement OpenAPI models blocks

.vscode/settings.json

@@ -11,6 +11,7 @@
     "prettier.enable": false,
     "editor.defaultFormatter": "biomejs.biome",
     "editor.codeActionsOnSave": {
-        "source.organizeImports.biome": "explicit"
+        "source.organizeImports.biome": "explicit",
+        "source.fixAll.biome": "explicit"
     }
 }

packages/gitbook/src/components/DocumentView/OpenAPI/OpenAPI.tsx

@@ -2,7 +2,7 @@ import type { JSONDocument } from '@gitbook/api';
 import { Icon } from '@gitbook/icons';
 import { OpenAPIOperation } from '@gitbook/react-openapi';
 
-import { type AnyOpenAPIOperationBlock, resolveOpenAPIBlock } from '@/lib/openapi/fetch';
+import { resolveOpenAPIOperationBlock } from '@/lib/openapi/resolveOpenAPIOperationBlock';
 import { tcls } from '@/lib/tailwind';
 
 import type { BlockProps } from '../Block';
@@ -12,11 +12,12 @@ import { Heading } from '../Heading';
 
 import './scalar.css';
 import './style.css';
+import type { AnyOpenAPIBlock } from '@/lib/openapi/types';
 
 /**
  * Render an openapi block or an openapi-operation block.
  */
-export async function OpenAPI(props: BlockProps<AnyOpenAPIOperationBlock>) {
+export async function OpenAPI(props: BlockProps<AnyOpenAPIBlock>) {
     const { style } = props;
     return (
         <div className={tcls('flex w-full', style, 'max-w-full')}>
@@ -25,14 +26,14 @@ export async function OpenAPI(props: BlockProps<AnyOpenAPIOperationBlock>) {
     );
 }
 
-async function OpenAPIBody(props: BlockProps<AnyOpenAPIOperationBlock>) {
+async function OpenAPIBody(props: BlockProps<AnyOpenAPIBlock>) {
     const { block, context } = props;
 
     if (!context.contentContext) {
         return null;
     }
 
-    const { data, specUrl, error } = await resolveOpenAPIBlock({
+    const { data, specUrl, error } = await resolveOpenAPIOperationBlock({
         block,
         context: context.contentContext,
     });

packages/gitbook/src/components/DocumentView/OpenAPI/style.css

@@ -3,6 +3,10 @@
     @apply flex-1 flex flex-col gap-4 mb-14;
 }
 
+.openapi-models {
+    @apply flex flex-col mb-14 flex-1;
+}
+
 .openapi-columns {
     @apply grid grid-cols-1 lg:grid-cols-2 gap-6 print-mode:grid-cols-1 justify-stretch;
 }
@@ -615,3 +619,11 @@
 .openapi-section-body.openapi-schema.openapi-schema-root {
     @apply space-y-2.5;
 }
+
+.openapi-section-models {
+    @apply border border-tint-subtle rounded-lg;
+}
+
+.openapi-section-models > .openapi-section-body > .openapi-schema-properties > .openapi-schema {
+    @apply p-2.5;
+}

packages/gitbook/src/lib/document-sections.ts

@@ -2,7 +2,7 @@ import type { JSONDocument } from '@gitbook/api';
 import type { GitBookAnyContext } from '@v2/lib/context';
 
 import { getNodeText } from './document';
-import { resolveOpenAPIBlock } from './openapi/fetch';
+import { resolveOpenAPIOperationBlock } from './openapi/resolveOpenAPIOperationBlock';
 
 export interface DocumentSection {
     id: string;
@@ -38,7 +38,7 @@ export async function getDocumentSections(
         }
 
         if ((block.type === 'swagger' || block.type === 'openapi-operation') && block.meta?.id) {
-            const { data: operation } = await resolveOpenAPIBlock({
+            const { data: operation } = await resolveOpenAPIOperationBlock({
                 block,
                 context,
             });

packages/gitbook/src/lib/openapi/fetch.ts

@@ -1,82 +1,40 @@
-import type { DocumentBlockOpenAPI, DocumentBlockOpenAPIOperation } from '@gitbook/api';
-import { OpenAPIParseError, parseOpenAPI } from '@gitbook/openapi-parser';
-import { type OpenAPIOperationData, resolveOpenAPIOperation } from '@gitbook/react-openapi';
-import type { GitBookAnyContext } from '@v2/lib/context';
+import { parseOpenAPI } from '@gitbook/openapi-parser';
 
 import { type CacheFunctionOptions, cache, noCacheFetchOptions } from '@/lib/cache';
-
+import type { ResolveOpenAPIBlockArgs } from '@/lib/openapi/types';
 import { assert } from 'ts-essentials';
 import { resolveContentRef } from '../references';
 import { isV2 } from '../v2';
 import { enrichFilesystem } from './enrich';
+import type { FetchOpenAPIFilesystemResult } from './types';
 
-export type AnyOpenAPIOperationBlock = DocumentBlockOpenAPI | DocumentBlockOpenAPIOperation;
-
-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)!;
-    }
-
-    const result = baseResolveOpenAPIBlock(args);
-    weakmap.set(args.block, result);
-    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.
+ * Fetch OpenAPI block.
  */
-async function baseResolveOpenAPIBlock(
+export async function fetchOpenAPIFilesystem(
     args: ResolveOpenAPIBlockArgs
-): Promise<ResolveOpenAPIBlockResult> {
+): Promise<FetchOpenAPIFilesystemResult> {
     const { context, block } = args;
-    if (!block.data.path || !block.data.method) {
-        return { data: null, specUrl: null };
-    }
 
     const ref = block.data.ref;
     const resolved = ref ? await resolveContentRef(ref, context) : null;
 
     if (!resolved) {
-        return { data: null, specUrl: null };
+        return { filesystem: null, specUrl: null };
     }
 
-    try {
-        const filesystem = await (() => {
-            if (ref.kind === 'openapi') {
-                assert(resolved.openAPIFilesystem);
-                return resolved.openAPIFilesystem;
-            }
-            return fetchFilesystem(resolved.href);
-        })();
-
-        const data = await resolveOpenAPIOperation(filesystem, {
-            path: block.data.path,
-            method: block.data.method,
-        });
-
-        return { data, specUrl: resolved.href };
-    } catch (error) {
-        if (error instanceof OpenAPIParseError) {
-            return { error };
+    const filesystem = await (() => {
+        if (ref.kind === 'openapi') {
+            assert(resolved.openAPIFilesystem);
+            return resolved.openAPIFilesystem;
         }
+        return fetchFilesystem(resolved.href);
+    })();
 
-        throw error;
-    }
+    return {
+        filesystem,
+        specUrl: resolved.href,
+    };
 }
 
 function fetchFilesystem(url: string) {

packages/gitbook/src/lib/openapi/resolveOpenAPIModelsBlock.ts

@@ -0,0 +1,55 @@
+import { fetchOpenAPIFilesystem } from '@/lib/openapi/fetch';
+import type { ResolveOpenAPIBlockResult } from '@/lib/openapi/types';
+import { OpenAPIParseError } from '@gitbook/openapi-parser';
+import { type OpenAPIModelsData, resolveOpenAPIModels } from '@gitbook/react-openapi';
+import type { AnyOpenAPIBlock, ResolveOpenAPIBlockArgs } from './types';
+
+type ResolveOpenAPIModelsBlockResult = ResolveOpenAPIBlockResult<OpenAPIModelsData>;
+
+const weakmap = new WeakMap<AnyOpenAPIBlock, Promise<ResolveOpenAPIModelsBlockResult>>();
+
+/**
+ * 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 resolveOpenAPIModelsBlock(
+    args: ResolveOpenAPIBlockArgs
+): Promise<ResolveOpenAPIModelsBlockResult> {
+    if (weakmap.has(args.block)) {
+        return weakmap.get(args.block)!;
+    }
+
+    const result = baseResolveOpenAPIModelsBlock(args);
+    weakmap.set(args.block, result);
+    return result;
+}
+
+/**
+ * Resolve OpenAPI models block.
+ */
+async function baseResolveOpenAPIModelsBlock(
+    args: ResolveOpenAPIBlockArgs
+): Promise<ResolveOpenAPIModelsBlockResult> {
+    const { context, block } = args;
+    if (!block.data.path || !block.data.method) {
+        return { data: null, specUrl: null };
+    }
+
+    try {
+        const { filesystem, specUrl } = await fetchOpenAPIFilesystem({ block, context });
+
+        if (!filesystem || !specUrl) {
+            return { data: null, specUrl: null };
+        }
+
+        const data = await resolveOpenAPIModels(filesystem);
+
+        return { data, specUrl };
+    } catch (error) {
+        if (error instanceof OpenAPIParseError) {
+            return { error };
+        }
+
+        throw error;
+    }
+}

packages/gitbook/src/lib/openapi/resolveOpenAPIOperationBlock.ts

@@ -0,0 +1,57 @@
+import { fetchOpenAPIFilesystem } from '@/lib/openapi/fetch';
+import { OpenAPIParseError } from '@gitbook/openapi-parser';
+import { type OpenAPIOperationData, resolveOpenAPIOperation } from '@gitbook/react-openapi';
+import type { AnyOpenAPIBlock, ResolveOpenAPIBlockArgs, ResolveOpenAPIBlockResult } from './types';
+
+type ResolveOpenAPIOperationBlockResult = ResolveOpenAPIBlockResult<OpenAPIOperationData>;
+
+const weakmap = new WeakMap<AnyOpenAPIBlock, Promise<ResolveOpenAPIOperationBlockResult>>();
+
+/**
+ * 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 resolveOpenAPIOperationBlock(
+    args: ResolveOpenAPIBlockArgs
+): Promise<ResolveOpenAPIOperationBlockResult> {
+    if (weakmap.has(args.block)) {
+        return weakmap.get(args.block)!;
+    }
+
+    const result = baseResolveOpenAPIOperationBlock(args);
+    weakmap.set(args.block, result);
+    return result;
+}
+
+/**
+ * Resolve OpenAPI operation block.
+ */
+async function baseResolveOpenAPIOperationBlock(
+    args: ResolveOpenAPIBlockArgs
+): Promise<ResolveOpenAPIOperationBlockResult> {
+    const { context, block } = args;
+    if (!block.data.path || !block.data.method) {
+        return { data: null, specUrl: null };
+    }
+
+    try {
+        const { filesystem, specUrl } = await fetchOpenAPIFilesystem({ block, context });
+
+        if (!filesystem) {
+            return { data: null, specUrl: null };
+        }
+
+        const data = await resolveOpenAPIOperation(filesystem, {
+            path: block.data.path,
+            method: block.data.method,
+        });
+
+        return { data, specUrl };
+    } catch (error) {
+        if (error instanceof OpenAPIParseError) {
+            return { error };
+        }
+
+        throw error;
+    }
+}

packages/gitbook/src/lib/openapi/types.ts

@@ -0,0 +1,50 @@
+import type { DocumentBlockOpenAPI, DocumentBlockOpenAPIOperation } from '@gitbook/api';
+import type { Filesystem, OpenAPIParseError, OpenAPIV3xDocument } from '@gitbook/openapi-parser';
+import type { GitBookAnyContext } from '@v2/lib/context';
+
+//!!TODO: Add DocumentBlockOpenAPIModels when available in @gitbook/api
+export type AnyOpenAPIBlock = DocumentBlockOpenAPI | DocumentBlockOpenAPIOperation;
+
+/**
+ * Arguments for resolving OpenAPI block.
+ */
+export type ResolveOpenAPIBlockArgs = {
+    block: AnyOpenAPIBlock;
+    context: GitBookAnyContext;
+};
+
+/**
+ * Fetch OpenAPI filesystem result.
+ */
+export type FetchOpenAPIFilesystemResult =
+    | {
+          error?: undefined;
+          filesystem: Filesystem<OpenAPIV3xDocument> | null;
+          specUrl: string | null;
+      }
+    | FetchOpenAPIFilesystemError;
+
+/**
+ * Fetch OpenAPI filesystem error.
+ */
+type FetchOpenAPIFilesystemError = {
+    error: OpenAPIParseError;
+    filesystem?: undefined;
+    specUrl?: undefined;
+};
+
+/**
+ * Resolved OpenAPI block result.
+ */
+export type ResolveOpenAPIBlockResult<T> =
+    | { error?: undefined; data: T | null; specUrl: string | null }
+    | ResolveOpenAPIBlockError;
+
+/**
+ * Resolved OpenAPI block error.
+ */
+type ResolveOpenAPIBlockError = {
+    error: OpenAPIParseError;
+    data?: undefined;
+    specUrl?: undefined;
+};

packages/openapi-parser/src/traverse.ts

@@ -29,12 +29,20 @@ export async function traverse<T extends AnyObject | AnyObject[]>(
     }
 
     const keys = Object.keys(specification);
-    await Promise.all(
-        keys.map(async (key) => {
+    const results = await Promise.all(
+        keys.map(async (key, index) => {
             const value = specification[key];
-            result[key] = await traverse(value, transform, [...path, key], seen);
+            const processed = await traverse(value, transform, [...path, key], seen);
+            return { key, value: processed, index };
         })
     );
 
+    // Promise.all does not guarantee the order of the results
+    // So we need to sort them to preserve the original order
+    results.sort((a, b) => a.index - b.index);
+    for (const { key, value } of results) {
+        result[key] = value;
+    }
+
     return transform(result, path) as Promise<T>;
 }