Improve OpenAPI schema style (#3079)

Author: nolannbiron

.changeset/ninety-sloths-think.md

@@ -0,0 +1,6 @@
+---
+'@gitbook/react-openapi': patch
+'gitbook': patch
+---
+
+Improve OpenAPI schema style

packages/gitbook/src/components/DocumentView/OpenAPI/style.css

@@ -151,6 +151,10 @@
     /* unstyled */
 }
 
+.openapi-schema-root-description.openapi-markdown {
+    @apply prose-sm text-balance mt-1.5 !text-[0.813rem] text-tint overflow-hidden !font-normal select-text prose-strong:font-semibold prose-strong:text-inherit;
+}
+
 .openapi-schema-properties {
     @apply flex flex-col;
 }
@@ -199,7 +203,7 @@
 .openapi-schema-name {
     /* To make double click on the property name select only the name,
     we disable selection on the parent and re-enable it on the children. */
-    @apply select-none flex gap-x-2.5 items-baseline text-sm flex-wrap;
+    @apply select-none text-sm text-balance *:whitespace-nowrap flex flex-wrap gap-y-1.5 gap-x-2.5;
 }
 
 .openapi-schema-name .openapi-deprecated {
@@ -278,7 +282,7 @@
 
 /* Schema Description */
 .openapi-schema-description.openapi-markdown {
-    @apply prose-sm text-tint overflow-hidden !font-normal select-text prose-strong:font-semibold prose-strong:text-inherit;
+    @apply prose-sm text-tint overflow-hidden text-pretty !font-normal select-text prose-strong:font-semibold prose-strong:text-inherit;
 }
 
 .openapi-schema-description.openapi-markdown pre:has(code) {
@@ -298,13 +302,15 @@
 
 /* Schema Examples */
 .openapi-schema-example,
-.openapi-schema-pattern {
+.openapi-schema-pattern,
+.openapi-schema-default {
     @apply prose-sm text-tint;
 }
 
 .openapi-schema-example code,
 .openapi-schema-pattern code,
-.openapi-schema-enum-value code {
+.openapi-schema-enum-value code,
+.openapi-schema-default code {
     @apply py-px px-1 min-w-[1.625rem] text-tint-strong font-normal w-fit justify-center items-center ring-1 ring-inset ring-tint bg-tint rounded text-xs leading-[calc(max(1.20em,1.25rem))] before:!content-none after:!content-none;
 }
 
@@ -318,7 +324,7 @@
 }
 
 .openapi-securities-description.openapi-markdown {
-    @apply prose-sm text-tint !font-normal select-text prose-strong:font-semibold prose-strong:text-inherit;
+    @apply prose-sm text-tint !font-normal select-text text-pretty prose-strong:font-semibold prose-strong:text-inherit;
 }
 
 .openapi-securities-label {
@@ -344,7 +350,7 @@
 }
 
 .openapi-requestbody-description.openapi-markdown {
-    @apply prose-sm text-tint !font-normal select-text prose-strong:font-semibold prose-strong:text-inherit;
+    @apply prose-sm text-tint !font-normal text-pretty select-text prose-strong:font-semibold prose-strong:text-inherit;
 }
 
 /* Responses */
@@ -361,7 +367,7 @@
 }
 
 .openapi-response-description.openapi-markdown {
-    @apply text-left prose-sm text-[0.813rem] h-auto relative leading-[1.125rem] text-tint !font-normal truncate select-text prose-strong:font-semibold prose-strong:text-inherit;
+    @apply text-left prose-sm text-[0.813rem] text-pretty h-auto relative leading-[1.125rem] text-tint !font-normal truncate select-text prose-strong:font-semibold prose-strong:text-inherit;
 }
 
 .openapi-response-description.openapi-markdown::-webkit-scrollbar {

packages/react-openapi/src/OpenAPISchema.tsx

@@ -11,6 +11,7 @@ import { OpenAPICopyButton } from './OpenAPICopyButton';
 import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 import { OpenAPISchemaName } from './OpenAPISchemaName';
 import { retrocycle } from './decycle';
+import { stringifyOpenAPI } from './stringifyOpenAPI';
 import type { OpenAPIClientContext } from './types';
 import { checkIsReference, resolveDescription, resolveFirstExample } from './utils';
 
@@ -145,17 +146,23 @@ function OpenAPIRootSchema(props: {
 
     const id = useId();
     const properties = getSchemaProperties(schema);
+    const description = resolveDescription(schema);
 
     if (properties?.length) {
         const circularRefs = new Map(parentCircularRefs);
         circularRefs.set(schema, id);
 
         return (
-            <OpenAPISchemaProperties
-                properties={properties}
-                circularRefs={circularRefs}
-                context={context}
-            />
+            <>
+                {description ? (
+                    <Markdown source={description} className="openapi-schema-root-description" />
+                ) : null}
+                <OpenAPISchemaProperties
+                    properties={properties}
+                    circularRefs={circularRefs}
+                    context={context}
+                />
+            </>
         );
     }
 
@@ -322,15 +329,25 @@ function OpenAPISchemaPresentation(props: { property: OpenAPISchemaPropertyEntry
             {description ? (
                 <Markdown source={description} className="openapi-schema-description" />
             ) : null}
+            {schema.default !== undefined ? (
+                <span className="openapi-schema-default">
+                    Default:{' '}
+                    <code>
+                        {typeof schema.default === 'string' && schema.default
+                            ? schema.default
+                            : stringifyOpenAPI(schema.default)}
+                    </code>
+                </span>
+            ) : null}
             {typeof example === 'string' ? (
-                <div className="openapi-schema-example">
+                <span className="openapi-schema-example">
                     Example: <code>{example}</code>
-                </div>
+                </span>
             ) : null}
             {schema.pattern ? (
-                <div className="openapi-schema-pattern">
+                <span className="openapi-schema-pattern">
                     Pattern: <code>{schema.pattern}</code>
-                </div>
+                </span>
             ) : null}
             <OpenAPISchemaEnum schema={schema} />
         </div>

packages/react-openapi/src/OpenAPISchemaName.tsx

@@ -1,6 +1,5 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import type React from 'react';
-import { stringifyOpenAPI } from './stringifyOpenAPI';
 
 interface OpenAPISchemaNameProps {
     schema?: OpenAPIV3.SchemaObject;
@@ -19,7 +18,7 @@ export function OpenAPISchemaName(props: OpenAPISchemaNameProps) {
     const additionalItems = schema && getAdditionalItems(schema);
 
     return (
-        <div className="openapi-schema-name">
+        <span className="openapi-schema-name">
             {propertyName ? (
                 <span data-deprecated={schema?.deprecated} className="openapi-schema-propertyname">
                     {propertyName}
@@ -41,7 +40,7 @@ export function OpenAPISchemaName(props: OpenAPISchemaNameProps) {
                 <span className="openapi-schema-optional">optional</span>
             )}
             {schema?.deprecated ? <span className="openapi-deprecated">Deprecated</span> : null}
-        </div>
+        </span>
     );
 }
 
@@ -56,11 +55,6 @@ function getAdditionalItems(schema: OpenAPIV3.SchemaObject): string {
         additionalItems += ` · max: ${schema.maximum || schema.maxLength || schema.maxItems}`;
     }
 
-    // If the schema has a default value, we display it
-    if (typeof schema.default !== 'undefined') {
-        additionalItems += ` · default: ${stringifyOpenAPI(schema.default)}`;
-    }
-
     if (schema.nullable) {
         additionalItems = ' | nullable';
     }