Improve OpenAPI abstraction to be more flexible on usage (#2832)

Author: gregberge

.changeset/honest-ants-appear.md

@@ -0,0 +1,7 @@
+---
+'@gitbook/openapi-parser': patch
+'@gitbook/react-openapi': patch
+'gitbook': patch
+---
+
+Improve the OpenAPI package API

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

@@ -33,7 +33,7 @@ async function OpenAPIBody(props: BlockProps<DocumentBlockOpenAPI>) {
         return (
             <div className={tcls('hidden')}>
                 <p>
-                    Error with {error.url}: {error.message}
+                    Error with {error.rootURL}: {error.message}
                 </p>
             </div>
         );

packages/gitbook/src/lib/openapi.ts

@@ -1,10 +1,6 @@
 import { ContentRef, DocumentBlockOpenAPI } from '@gitbook/api';
 import { parseOpenAPI, OpenAPIParseError, traverse } from '@gitbook/openapi-parser';
-import {
-    OpenAPIOperationData,
-    fetchOpenAPIOperation,
-    OpenAPIFetcher,
-} from '@gitbook/react-openapi';
+import { type OpenAPIOperationData, resolveOpenAPIOperation } from '@gitbook/react-openapi';
 
 import { cache, noCacheFetchOptions, CacheFunctionOptions } from '@/lib/cache';
 
@@ -27,14 +23,11 @@ export async function fetchOpenAPIBlock(
     }
 
     try {
-        const data = await fetchOpenAPIOperation(
-            {
-                url: resolved.href,
-                path: block.data.path,
-                method: block.data.method,
-            },
-            fetcher,
-        );
+        const filesystem = await fetchFilesystem(resolved.href);
+        const data = await resolveOpenAPIOperation(filesystem, {
+            path: block.data.path,
+            method: block.data.method,
+        });
 
         return { data, specUrl: resolved.href };
     } catch (error) {
@@ -46,50 +39,44 @@ export async function fetchOpenAPIBlock(
     }
 }
 
-const fetcher: OpenAPIFetcher = {
-    fetch: cache({
-        name: 'openapi.fetch.v5',
-        get: async (url: string, options: CacheFunctionOptions) => {
-            // Wrap the raw string to prevent invalid URLs from being passed to fetch.
-            // This can happen if the URL has whitespace, which is currently handled differently by Cloudflare's implementation of fetch:
-            // https://github.com/cloudflare/workerd/issues/1957
-            const response = await fetch(new URL(url), {
-                ...noCacheFetchOptions,
-                signal: options.signal,
-            });
+const fetchFilesystem = cache({
+    name: 'openapi.fetch.v5',
+    get: async (url: string, options: CacheFunctionOptions) => {
+        // Wrap the raw string to prevent invalid URLs from being passed to fetch.
+        // This can happen if the URL has whitespace, which is currently handled differently by Cloudflare's implementation of fetch:
+        // https://github.com/cloudflare/workerd/issues/1957
+        const response = await fetch(new URL(url), {
+            ...noCacheFetchOptions,
+            signal: options.signal,
+        });
 
-            if (!response.ok) {
-                throw new Error(
-                    `Failed to fetch OpenAPI file: ${response.status} ${response.statusText}`,
-                );
-            }
+        if (!response.ok) {
+            throw new Error(
+                `Failed to fetch OpenAPI file: ${response.status} ${response.statusText}`,
+            );
+        }
 
-            const text = await response.text();
-            const filesystem = await parseOpenAPI({ url, value: text });
-            const cache: Map<string, Promise<string>> = new Map();
-            const transformedFs = await traverse(filesystem, async (node) => {
-                if (
-                    'description' in node &&
-                    typeof node.description === 'string' &&
-                    node.description
-                ) {
-                    if (cache.has(node.description)) {
-                        node['x-description-html'] = await cache.get(node.description);
-                    } else {
-                        const promise = parseMarkdown(node.description);
-                        cache.set(node.description, promise);
-                        node['x-description-html'] = await promise;
-                    }
+        const text = await response.text();
+        const filesystem = await parseOpenAPI({ value: text, rootURL: url });
+        const cache: Map<string, Promise<string>> = new Map();
+        const transformedFs = await traverse(filesystem, async (node) => {
+            if ('description' in node && typeof node.description === 'string' && node.description) {
+                if (cache.has(node.description)) {
+                    node['x-description-html'] = await cache.get(node.description);
+                } else {
+                    const promise = parseMarkdown(node.description);
+                    cache.set(node.description, promise);
+                    node['x-description-html'] = await promise;
                 }
-                return node;
-            });
-            return {
-                // Cache for 4 hours
-                ttl: 24 * 60 * 60,
-                // Revalidate every 2 hours
-                revalidateBefore: 22 * 60 * 60,
-                data: transformedFs,
-            };
-        },
-    }),
-};
+            }
+            return node;
+        });
+        return {
+            // Cache for 4 hours
+            ttl: 24 * 60 * 60,
+            // Revalidate every 2 hours
+            revalidateBefore: 22 * 60 * 60,
+            data: transformedFs,
+        };
+    },
+});

packages/openapi-parser/src/error.ts

@@ -1,14 +1,28 @@
+type OpenAPIParseErrorCode =
+    | 'invalid'
+    | 'parse-v2-in-v3'
+    | 'v2-conversion'
+    | 'dereference'
+    | 'yaml-parse';
+
 /**
  * Error thrown when the OpenAPI document is invalid.
  */
 export class OpenAPIParseError extends Error {
     public override name = 'OpenAPIParseError';
+    public code: OpenAPIParseErrorCode;
+    public rootURL: string | null;
 
     constructor(
         message: string,
-        public readonly url: string,
-        public readonly code?: 'invalid-spec' | 'v2-spec' | 'failed-dereference',
+        options: {
+            code: OpenAPIParseErrorCode;
+            rootURL?: string | null;
+            cause?: Error;
+        },
     ) {
-        super(message);
+        super(message, { cause: options.cause });
+        this.code = options.code;
+        this.rootURL = options.rootURL ?? null;
     }
 }

packages/openapi-parser/src/filesystem.test.ts

@@ -34,7 +34,7 @@ describe('#createFileSystem', () => {
         const url = new URL('/root/spec.yaml', server.url).href;
         const filesystem = await createFileSystem({
             value: url,
-            baseUrl: url,
+            rootURL: url,
         });
         expect(filesystem).toHaveLength(4);
         expect(filesystem[0]!.isEntrypoint).toBe(true);

packages/openapi-parser/src/filesystem.ts

@@ -1,17 +1,24 @@
 import { type AnyApiDefinitionFormat, load } from '@scalar/openapi-parser';
-import { fetchUrls } from './scalar-plugins/fetchURLs';
+import { fetchURLs } from './scalar-plugins/fetchURLs';
 import type { Filesystem } from './types';
 
 /**
  * Create a filesystem from an OpenAPI document.
  * Fetches all the URLs specified in references and builds a filesystem.
  */
 export async function createFileSystem(input: {
+    /**
+     * The OpenAPI document to create the filesystem from.
+     */
     value: AnyApiDefinitionFormat;
-    baseUrl: string;
+    /**
+     * The root URL of the specified OpenAPI document.
+     * Used to resolve relative URLs.
+     */
+    rootURL: string | null;
 }): Promise<Filesystem> {
     const { filesystem } = await load(input.value, {
-        plugins: [fetchUrls({ baseUrl: input.baseUrl })],
+        plugins: [fetchURLs({ rootURL: input.rootURL })],
     });
     return filesystem;
 }

packages/openapi-parser/src/parse.test.ts

@@ -7,7 +7,7 @@ describe('#parseOpenAPI', () => {
     it('parses an OpenAPI document', async () => {
         const schema = await parseOpenAPI({
             value: spec,
-            url: 'https://example.com',
+            rootURL: null,
         });
         // Ensure the structure returned is not recursive (not dereferenced).
         JSON.stringify(schema);

packages/openapi-parser/src/parse.ts

@@ -1,3 +1,4 @@
+import { AnyApiDefinitionFormat } from '@scalar/openapi-parser';
 import { OpenAPIParseError } from './error';
 import { convertOpenAPIV2ToOpenAPIV3 } from './v2';
 import { parseOpenAPIV3 } from './v3';
@@ -7,11 +8,20 @@ import { parseOpenAPIV3 } from './v3';
  * It will also convert Swagger 2.0 to OpenAPI 3.0.
  * It can throw an `OpenAPIParseError` if the document is invalid.
  */
-export async function parseOpenAPI(input: { value: string; url: string }) {
+export async function parseOpenAPI(input: {
+    /**
+     * The API definition to parse.
+     */
+    value: AnyApiDefinitionFormat;
+    /**
+     * The root URL of the specified OpenAPI document.
+     */
+    rootURL: string | null;
+}) {
     try {
         return await parseOpenAPIV3(input);
     } catch (error) {
-        if (error instanceof OpenAPIParseError && error.code === 'v2-spec') {
+        if (error instanceof OpenAPIParseError && error.code === 'parse-v2-in-v3') {
             return convertOpenAPIV2ToOpenAPIV3(input);
         }
         throw error;

packages/openapi-parser/src/scalar-plugins/fetchURLs.ts

@@ -4,11 +4,11 @@ export const fetchUrlsDefaultConfiguration = {
     limit: 40,
 };
 
-export const fetchUrls: (customConfiguration: {
+export const fetchURLs: (customConfiguration: {
     /**
-     * Base URL to use for relative paths.
+     * Root URL to resolve relative URLs.
      */
-    baseUrl: string;
+    rootURL: string | null;
 
     /**
      * Limit the number of requests. Set to `false` to disable the limit.
@@ -53,7 +53,7 @@ export const fetchUrls: (customConfiguration: {
 
             try {
                 numberOfRequests++;
-                const url = getReferenceUrl(value, configuration.baseUrl);
+                const url = getReferenceUrl({ value, rootURL: configuration.rootURL });
                 const response = await fetch(url);
                 return await response.text();
             } catch (error: any) {
@@ -66,6 +66,7 @@ export const fetchUrls: (customConfiguration: {
 
 /**
  * Check if a path is relative.
+ * Meaning it does not start with http://, https://, www., data:, or #/.
  */
 function isRelativePath(path: string): boolean {
     // Exclude external URLs
@@ -76,9 +77,13 @@ function isRelativePath(path: string): boolean {
 /**
  * Get the reference URL.
  */
-function getReferenceUrl(value: string, baseUrl: string) {
+function getReferenceUrl(input: { value: string; rootURL: string | null }) {
+    const { value, rootURL } = input;
     if (isRelativePath(value)) {
-        return new URL(value, baseUrl).href;
+        if (!rootURL) {
+            throw new Error(`[fetchUrls] Cannot resolve relative path without rootURL (${value})`);
+        }
+        return new URL(value, rootURL).href;
     }
 
     return value;

packages/openapi-parser/src/traverse.test.ts

@@ -35,7 +35,7 @@ describe('#traverse', () => {
     it('traverses a complete filesystem', async () => {
         const filesystem = await createFileSystem({
             value: JSON.parse(recursiveSpec),
-            baseUrl: 'https://example.com',
+            rootURL: 'https://example.com',
         });
 
         const transformedFilesystem = await traverse(filesystem, async (node) => {