Fix after review

Author: nolannbiron

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/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,122 +1,40 @@
-import type { DocumentBlockOpenAPI, DocumentBlockOpenAPIOperation } from '@gitbook/api';
-import { OpenAPIParseError, parseOpenAPI } from '@gitbook/openapi-parser';
-import {
-    type OpenAPIModelsData,
-    type OpenAPIOperationData,
-    resolveOpenAPIModels,
-    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';
-
-//!!TODO: Add DocumentBlockOpenAPIModels when available in @gitbook/api
-export type AnyOpenAPIOperationBlock = DocumentBlockOpenAPI | DocumentBlockOpenAPIOperation;
-
-export type OpenAPIBlockType = 'operation' | 'models';
-
-export type OpenAPIOperationResult = {
-    data: OpenAPIOperationData | null;
-    error: undefined;
-    specUrl: string | null;
-};
-
-export type OpenAPIModelsResult = {
-    data: OpenAPIModelsData | null;
-    error: undefined;
-    specUrl: string | null;
-};
-
-export type OpenAPIErrorResult = {
-    data?: undefined;
-    specUrl?: undefined;
-    error: OpenAPIParseError;
-};
-
-export type OpenAPIBlockResult<T extends OpenAPIBlockType = 'operation'> =
-    | (T extends 'operation' ? OpenAPIOperationResult : OpenAPIModelsResult)
-    | OpenAPIErrorResult;
-
-type ResolveOpenAPIBlockArgs<T = 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<OpenAPIBlockResult>>();
+import type { FetchOpenAPIFilesystemResult } from './types';
 
 /**
- * Cache the result of resolving an OpenAPI block.
- * It is important because the resolve is called in sections and in the block itself.
+ * Fetch OpenAPI block.
  */
-export function resolveOpenAPIBlock<T extends OpenAPIBlockType = 'operation'>(
-    args: ResolveOpenAPIBlockArgs<T>
-): Promise<OpenAPIBlockResult<T>> {
-    if (weakmap.has(args.block)) {
-        // We enforce the type here cause weakmap doesn't know the type of the value
-        return weakmap.get(args.block) as Promise<OpenAPIBlockResult<T>>;
-    }
-
-    const result = baseResolveOpenAPIBlock(args);
-    weakmap.set(args.block, result as Promise<OpenAPIBlockResult>);
-    return result;
-}
-
-/**
- * Resolve OpenAPI block.
- */
-async function baseResolveOpenAPIBlock<T extends OpenAPIBlockType = 'operation'>(
-    args: ResolveOpenAPIBlockArgs<T>
-): Promise<OpenAPIBlockResult<T>> {
-    const { context, block, type = 'operation' } = args;
-    if (!block.data.path || !block.data.method) {
-        return createResults<T>(null);
-    }
+export async function fetchOpenAPIFilesystem(
+    args: ResolveOpenAPIBlockArgs
+): Promise<FetchOpenAPIFilesystemResult> {
+    const { context, block } = args;
 
     const ref = block.data.ref;
     const resolved = ref ? await resolveContentRef(ref, context) : null;
 
     if (!resolved) {
-        return createResults<T>(null);
+        return { filesystem: null, specUrl: null };
     }
 
-    try {
-        const filesystem = await (() => {
-            if (ref.kind === 'openapi') {
-                assert(resolved.openAPIFilesystem);
-                return resolved.openAPIFilesystem;
-            }
-            return fetchFilesystem(resolved.href);
-        })();
-
-        let data: OpenAPIOperationData | OpenAPIModelsData | null = null;
-        if (type === 'models') {
-            data = await resolveOpenAPIModels(filesystem);
-        } else {
-            data = await resolveOpenAPIOperation(filesystem, {
-                path: block.data.path,
-                method: block.data.method,
-            });
+    const filesystem = await (() => {
+        if (ref.kind === 'openapi') {
+            assert(resolved.openAPIFilesystem);
+            return resolved.openAPIFilesystem;
         }
+        return fetchFilesystem(resolved.href);
+    })();
 
-        return createResults<T>(data, resolved.href);
-    } catch (error) {
-        if (error instanceof OpenAPIParseError) {
-            return { error };
-        }
-
-        throw error;
-    }
+    return {
+        filesystem,
+        specUrl: resolved.href,
+    };
 }
 
 function fetchFilesystem(url: string) {
@@ -181,17 +99,3 @@ async function fetchFilesystemUncached(
 
     return richFilesystem;
 }
-
-/**
- * Create a result for OpenAPI based on the type.
- */
-function createResults<T extends OpenAPIBlockType>(
-    data: OpenAPIOperationData | OpenAPIModelsData | null,
-    specUrl?: string
-): OpenAPIBlockResult<T> {
-    return {
-        error: undefined,
-        data,
-        specUrl,
-    } as OpenAPIBlockResult<T>;
-}

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

@@ -0,0 +1,53 @@
+import { fetchOpenAPIFilesystem } from '@/lib/openapi/fetch';
+import type { ResolveOpenAPIModelsBlockResult } from '@/lib/openapi/types';
+import { OpenAPIParseError } from '@gitbook/openapi-parser';
+import { resolveOpenAPIModels } from '@gitbook/react-openapi';
+import type { AnyOpenAPIBlock, ResolveOpenAPIBlockArgs } from './types';
+
+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,59 @@
+import { fetchOpenAPIFilesystem } from '@/lib/openapi/fetch';
+import { OpenAPIParseError } from '@gitbook/openapi-parser';
+import { resolveOpenAPIOperation } from '@gitbook/react-openapi';
+import type {
+    AnyOpenAPIBlock,
+    ResolveOpenAPIBlockArgs,
+    ResolveOpenAPIOperationBlockResult,
+} from './types';
+
+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,58 @@
+import type { DocumentBlockOpenAPI, DocumentBlockOpenAPIOperation } from '@gitbook/api';
+import type { Filesystem, OpenAPIParseError, OpenAPIV3xDocument } from '@gitbook/openapi-parser';
+import type { OpenAPIModelsData, OpenAPIOperationData } from '@gitbook/react-openapi';
+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 models block result.
+ */
+export type ResolveOpenAPIModelsBlockResult =
+    | { error?: undefined; data: OpenAPIModelsData | null; specUrl: string | null }
+    | ResolveOpenAPIBlockError;
+
+/**
+ * Resolved OpenAPI operation block result.
+ */
+export type ResolveOpenAPIOperationBlockResult =
+    | { error?: undefined; data: OpenAPIOperationData | null; specUrl: string | null }
+    | ResolveOpenAPIBlockError;
+
+/**
+ * Resolved OpenAPI block error.
+ */
+type ResolveOpenAPIBlockError = {
+    error: OpenAPIParseError;
+    data?: undefined;
+    specUrl?: undefined;
+};