@gitbook/react-openapi 1.0.4 → 1.1.0

package/src/utils.ts

@@ -1,4 +1,5 @@
 import type { AnyObject, OpenAPIV3, OpenAPIV3_1 } from '@gitbook/openapi-parser';
+import { stringifyOpenAPI } from './stringifyOpenAPI';
 
 export function checkIsReference(
     input: unknown
@@ -10,11 +11,19 @@ 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) {
+    return 'description' in object || 'x-gitbook-description-html' in object;
+}
+
 /**
  * Resolve the description of an object.
  */
 export function resolveDescription(object: OpenAPIV3.SchemaObject | AnyObject) {
-    if ('items' in object && object.items) {
+    // 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)) {
         return resolveDescription(object.items);
     }
 
@@ -50,9 +59,17 @@ export function resolveFirstExample(object: AnyObject) {
             return object.examples[firstKey];
         }
     }
-    if ('example' in object && object.example !== undefined) {
-        return object.example;
+
+    // Resolve top level example first
+    if (shouldDisplayExample(object)) {
+        return formatExample(object.example);
     }
+
+    // Resolve example from items if it exists
+    if (object.items && typeof object.items === 'object') {
+        return formatExample(object.items.example);
+    }
+
     return undefined;
 }
 
@@ -98,3 +115,34 @@ export function parameterToProperty(
         required: parameter.required,
     };
 }
+
+/**
+ * Format the example of a schema.
+ */
+function formatExample(example: unknown): string {
+    if (typeof example === 'string') {
+        return example
+            .replace(/\n/g, ' ') // Replace newlines with spaces
+            .replace(/\s+/g, ' ') // Collapse multiple spaces/newlines into a single space
+            .replace(/([\{\}:,])\s+/g, '$1 ') // Ensure a space after {, }, :, and ,
+            .replace(/\s+([\{\}:,])/g, ' $1') // Ensure a space before {, }, :, and ,
+            .trim();
+    }
+
+    return stringifyOpenAPI(example);
+}
+
+/**
+ * Check if an example should be displayed.
+ */
+function shouldDisplayExample(schema: OpenAPIV3.SchemaObject): boolean {
+    return (
+        (typeof schema.example === 'string' && !!schema.example) ||
+        typeof schema.example === 'number' ||
+        typeof schema.example === 'boolean' ||
+        (Array.isArray(schema.example) && schema.example.length > 0) ||
+        (typeof schema.example === 'object' &&
+            schema.example !== null &&
+            Object.keys(schema.example).length > 0)
+    );
+}