Fix example and description missing

Author: nolannbiron

packages/react-openapi/src/OpenAPISchema.tsx

@@ -5,9 +5,8 @@ import clsx from 'clsx';
 import { Markdown } from './Markdown';
 import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 import { OpenAPISchemaName } from './OpenAPISchemaName';
-import { stringifyOpenAPI } from './stringifyOpenAPI';
 import type { OpenAPIClientContext } from './types';
-import { checkIsReference, resolveDescription } from './utils';
+import { checkIsReference, resolveDescription, resolveFirstExample } from './utils';
 
 type CircularRefsIds = Map<OpenAPIV3.SchemaObject, string>;
 
@@ -199,30 +198,22 @@ export function OpenAPISchemaEnum(props: { enumValues: any[] }) {
     );
 }
 
-export function OpenAPISchemaPresentation(props: { property: OpenAPISchemaPropertyEntry }) {
+export function OpenAPISchemaPresentation(
+    props: { property: OpenAPISchemaPropertyEntry } & { showType?: boolean }
+) {
     const {
         property: { schema, propertyName, required },
+        showType = true,
     } = props;
 
-    const 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)
-        );
-    };
-
     const description = resolveDescription(schema);
+    const example = resolveFirstExample(schema);
 
     return (
         <div className="openapi-schema-presentation">
             <OpenAPISchemaName
                 schema={schema}
-                type={getSchemaTitle(schema)}
+                type={showType ? getSchemaTitle(schema) : undefined}
                 propertyName={propertyName}
                 required={required}
             />
@@ -237,9 +228,9 @@ export function OpenAPISchemaPresentation(props: { property: OpenAPISchemaProper
             {description ? (
                 <Markdown source={description} className="openapi-schema-description" />
             ) : null}
-            {shouldDisplayExample(schema) ? (
+            {example ? (
                 <div className="openapi-schema-example">
-                    Example: <code>{formatExample(schema.example)}</code>
+                    Example: <code>{example}</code>
                 </div>
             ) : null}
             {schema.pattern ? (
@@ -257,7 +248,9 @@ export function OpenAPISchemaPresentation(props: { property: OpenAPISchemaProper
 /**
  * Get the sub-properties of a schema.
  */
-function getSchemaProperties(schema: OpenAPIV3.SchemaObject): null | OpenAPISchemaPropertyEntry[] {
+export function getSchemaProperties(
+    schema: OpenAPIV3.SchemaObject
+): null | OpenAPISchemaPropertyEntry[] {
     // check array AND schema.items as this is sometimes null despite what the type indicates
     if (schema.type === 'array' && schema.items && !checkIsReference(schema.items)) {
         const items = schema.items;
@@ -418,16 +411,3 @@ function getDisclosureLabel(schema: OpenAPIV3.SchemaObject): string {
 
     return schema.title || 'child attributes';
 }
-
-function formatExample(example: any): 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);
-}

packages/react-openapi/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,23 @@ export function createStateKey(key: string, scope?: string) {
     return scope ? `${scope}_${key}` : key;
 }
 
+function hasDescription(object: AnyObject) {
+    if (Array.isArray(object)) {
+        return object.some(hasDescription);
+    }
+
+    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 ('items' in object && typeof object.items === 'object' && hasDescription(object.items)) {
+        if (Array.isArray(object.items)) {
+            return resolveDescription(object.items[0]);
+        }
+
         return resolveDescription(object.items);
     }
 
@@ -50,9 +63,20 @@ 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 any
+    if (object.items && typeof object.items === 'object') {
+        if (Array.isArray(object.items)) {
+            return formatExample(object.items[0].example);
+        }
+        return formatExample(object.items.example);
     }
+
     return undefined;
 }
 
@@ -98,3 +122,31 @@ 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);
+}
+
+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)
+    );
+}