Fixes

Author: nolannbiron

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

@@ -19,25 +19,29 @@ export type AnyOpenAPIOperationBlock = DocumentBlockOpenAPI | DocumentBlockOpenA
 
 export type OpenAPIBlockType = 'operation' | 'models';
 
-export type ResolveOpenAPIOperationBlockResult = {
-    error: undefined;
+export type OpenAPIOperationResult = {
     data: OpenAPIOperationData | null;
+    error: undefined;
     specUrl: string | null;
 };
 
-export type ResolveOpenAPIModelsBlockResult = {
-    error: undefined;
+export type OpenAPIModelsResult = {
     data: OpenAPIModelsData | null;
+    error: undefined;
     specUrl: string | null;
 };
 
-export type ResolveOpenAPIBlockResult<T extends OpenAPIBlockType = OpenAPIBlockType> =
-    | (T extends 'operation' ? ResolveOpenAPIOperationBlockResult : ResolveOpenAPIModelsBlockResult)
-    | ResolveOpenAPIBlockError;
+export type OpenAPIErrorResult = {
+    data?: undefined;
+    specUrl?: undefined;
+    error: OpenAPIParseError;
+};
 
-type ResolveOpenAPIBlockError = { error: OpenAPIParseError; data?: undefined; specUrl?: undefined };
+export type OpenAPIBlockResult<T extends OpenAPIBlockType = 'operation'> =
+    | (T extends 'operation' ? OpenAPIOperationResult : OpenAPIModelsResult)
+    | OpenAPIErrorResult;
 
-type ResolveOpenAPIBlockArgs<T extends OpenAPIBlockType = OpenAPIBlockType> = {
+type ResolveOpenAPIBlockArgs<T = OpenAPIBlockType> = {
     block: AnyOpenAPIOperationBlock;
     context: GitBookAnyContext;
     /**
@@ -48,21 +52,21 @@ type ResolveOpenAPIBlockArgs<T extends OpenAPIBlockType = OpenAPIBlockType> = {
     type?: T | OpenAPIBlockType;
 };
 
-const weakmap = new WeakMap<AnyOpenAPIOperationBlock, Promise<ResolveOpenAPIBlockResult>>();
+const weakmap = new WeakMap<AnyOpenAPIOperationBlock, Promise<OpenAPIBlockResult>>();
 
 /**
  * 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<T extends OpenAPIBlockType = 'operation'>(
     args: ResolveOpenAPIBlockArgs<T>
-): Promise<ResolveOpenAPIBlockResult<T>> {
+): Promise<OpenAPIBlockResult<T>> {
     if (weakmap.has(args.block)) {
-        return weakmap.get(args.block) as Promise<ResolveOpenAPIBlockResult<T>>;
+        return weakmap.get(args.block);
     }
 
     const result = baseResolveOpenAPIBlock(args);
-    weakmap.set(args.block, result as Promise<ResolveOpenAPIBlockResult<T>>);
+    weakmap.set(args.block, result as Promise<OpenAPIBlockResult>);
     return result;
 }
 
@@ -71,17 +75,17 @@ export function resolveOpenAPIBlock<T extends OpenAPIBlockType = 'operation'>(
  */
 async function baseResolveOpenAPIBlock<T extends OpenAPIBlockType = 'operation'>(
     args: ResolveOpenAPIBlockArgs<T>
-): Promise<ResolveOpenAPIBlockResult<T>> {
+): Promise<OpenAPIBlockResult<T>> {
     const { context, block, type = 'operation' } = args;
     if (!block.data.path || !block.data.method) {
-        return { data: null, specUrl: null } as ResolveOpenAPIBlockResult<T>;
+        return createResults(null);
     }
 
     const ref = block.data.ref;
     const resolved = ref ? await resolveContentRef(ref, context) : null;
 
     if (!resolved) {
-        return { data: null, specUrl: null } as ResolveOpenAPIBlockResult<T>;
+        return createResults(null);
     }
 
     try {
@@ -93,17 +97,17 @@ async function baseResolveOpenAPIBlock<T extends OpenAPIBlockType = 'operation'>
             return fetchFilesystem(resolved.href);
         })();
 
+        let data: OpenAPIOperationData | OpenAPIModelsData | null = null;
         if (type === 'models') {
-            const data = await resolveOpenAPIModels(filesystem);
-            return { data: data, specUrl: resolved.href } as ResolveOpenAPIBlockResult<T>;
+            data = await resolveOpenAPIModels(filesystem);
+        } else {
+            data = await resolveOpenAPIOperation(filesystem, {
+                path: block.data.path,
+                method: block.data.method,
+            });
         }
 
-        const data = await resolveOpenAPIOperation(filesystem, {
-            path: block.data.path,
-            method: block.data.method,
-        });
-
-        return { data, specUrl: resolved.href } as ResolveOpenAPIBlockResult<T>;
+        return createResults(data, resolved.href);
     } catch (error) {
         if (error instanceof OpenAPIParseError) {
             return { error };
@@ -175,3 +179,17 @@ async function fetchFilesystemUncached(
 
     return richFilesystem;
 }
+
+/**
+ * Create a result for OpenAPI based on the type.
+ */
+function createResults<T extends OpenAPIOperationData | OpenAPIModelsData>(
+    data: T | null,
+    specUrl?: string
+): OpenAPIBlockResult<T> {
+    return {
+        error: undefined,
+        data,
+        specUrl,
+    };
+}

packages/react-openapi/src/utils.ts

@@ -11,6 +11,9 @@ export function createStateKey(key: string, scope?: string) {
     return scope ? `${scope}_${key}` : key;
 }
 
+/**
+ * Check if an object has a description. Either at the root level or in items.
+ */
 function hasDescription(object: AnyObject) {
     if (Array.isArray(object)) {
         return object.some(hasDescription);
@@ -23,6 +26,7 @@ function hasDescription(object: AnyObject) {
  * Resolve the description of an object.
  */
 export function resolveDescription(object: OpenAPIV3.SchemaObject | AnyObject) {
+    // If the object has items and has a description, we resolve the description from items
     if ('items' in object && typeof object.items === 'object' && hasDescription(object.items)) {
         if (Array.isArray(object.items)) {
             return resolveDescription(object.items[0]);
@@ -69,7 +73,7 @@ export function resolveFirstExample(object: AnyObject) {
         return formatExample(object.example);
     }
 
-    // Resolve example from items if any
+    // Resolve example from items if it exists
     if (object.items && typeof object.items === 'object') {
         if (Array.isArray(object.items)) {
             return formatExample(object.items[0].example);
@@ -139,6 +143,9 @@ function formatExample(example: unknown): string {
     return stringifyOpenAPI(example);
 }
 
+/**
+ * Check if an example should be displayed.
+ */
 function shouldDisplayExample(schema: OpenAPIV3.SchemaObject): boolean {
     return (
         (typeof schema.example === 'string' && !!schema.example) ||