From 47573a6623779aed3e091e11ecd804309138f02f Mon Sep 17 00:00:00 2001 From: Nolann Biron Date: Wed, 2 Apr 2025 22:33:13 +0200 Subject: [PATCH 1/3] Improve OpenAPI schema style --- .changeset/ninety-sloths-think.md | 6 +++ .../components/DocumentView/OpenAPI/style.css | 20 ++++--- packages/react-openapi/src/OpenAPISchema.tsx | 52 +++++++++++++------ .../react-openapi/src/OpenAPISchemaName.tsx | 10 +--- 4 files changed, 58 insertions(+), 30 deletions(-) create mode 100644 .changeset/ninety-sloths-think.md diff --git a/.changeset/ninety-sloths-think.md b/.changeset/ninety-sloths-think.md new file mode 100644 index 0000000000..3ea4284266 --- /dev/null +++ b/.changeset/ninety-sloths-think.md @@ -0,0 +1,6 @@ +--- +'@gitbook/react-openapi': patch +'gitbook': patch +--- + +Improve OpenAPI schema style diff --git a/packages/gitbook/src/components/DocumentView/OpenAPI/style.css b/packages/gitbook/src/components/DocumentView/OpenAPI/style.css index 4f76998b14..e942e98c55 100644 --- a/packages/gitbook/src/components/DocumentView/OpenAPI/style.css +++ b/packages/gitbook/src/components/DocumentView/OpenAPI/style.css @@ -155,6 +155,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; } @@ -203,7 +207,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 { @@ -282,7 +286,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) { @@ -302,13 +306,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; } @@ -322,7 +328,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 { @@ -348,7 +354,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 */ @@ -365,7 +371,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 { diff --git a/packages/react-openapi/src/OpenAPISchema.tsx b/packages/react-openapi/src/OpenAPISchema.tsx index 435a2508bb..1d5b763d57 100644 --- a/packages/react-openapi/src/OpenAPISchema.tsx +++ b/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,27 +146,38 @@ 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 ( - + <> + {description ? ( + + ) : null} + + ); } return ( - + <> + {description ? ( + + ) : null} + + ); } @@ -322,15 +334,25 @@ function OpenAPISchemaPresentation(props: { property: OpenAPISchemaPropertyEntry {description ? ( ) : null} + {typeof schema.default !== 'undefined' ? ( + + Default:{' '} + + {typeof schema.default === 'string' && schema.default + ? schema.default + : stringifyOpenAPI(schema.default)} + + + ) : null} {typeof example === 'string' ? ( -
+ Example: {example} -
+ ) : null} {schema.pattern ? ( -
+ Pattern: {schema.pattern} -
+ ) : null} diff --git a/packages/react-openapi/src/OpenAPISchemaName.tsx b/packages/react-openapi/src/OpenAPISchemaName.tsx index 1c66cd3522..62934cb843 100644 --- a/packages/react-openapi/src/OpenAPISchemaName.tsx +++ b/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 ( -
+ {propertyName ? ( {propertyName} @@ -41,7 +40,7 @@ export function OpenAPISchemaName(props: OpenAPISchemaNameProps) { optional )} {schema?.deprecated ? Deprecated : null} -
+ ); } @@ -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'; } From dd5e903700bef98cc26ab04736750c9ef2565f42 Mon Sep 17 00:00:00 2001 From: Nolann Biron Date: Thu, 3 Apr 2025 09:06:17 +0200 Subject: [PATCH 2/3] Replace condition schema.default --- packages/react-openapi/src/OpenAPISchema.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/react-openapi/src/OpenAPISchema.tsx b/packages/react-openapi/src/OpenAPISchema.tsx index 1d5b763d57..4dea1ff8f9 100644 --- a/packages/react-openapi/src/OpenAPISchema.tsx +++ b/packages/react-openapi/src/OpenAPISchema.tsx @@ -334,7 +334,7 @@ function OpenAPISchemaPresentation(props: { property: OpenAPISchemaPropertyEntry {description ? ( ) : null} - {typeof schema.default !== 'undefined' ? ( + {schema.default !== undefined ? ( Default:{' '} From ce2aa63b5ede965a1644eeb11ab636e79b5ed88c Mon Sep 17 00:00:00 2001 From: Nolann Biron Date: Thu, 3 Apr 2025 16:21:34 +0200 Subject: [PATCH 3/3] Remove top-level description above OpenAPISchemaProperty --- packages/react-openapi/src/OpenAPISchema.tsx | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/packages/react-openapi/src/OpenAPISchema.tsx b/packages/react-openapi/src/OpenAPISchema.tsx index 4dea1ff8f9..89fe401998 100644 --- a/packages/react-openapi/src/OpenAPISchema.tsx +++ b/packages/react-openapi/src/OpenAPISchema.tsx @@ -167,17 +167,12 @@ function OpenAPIRootSchema(props: { } return ( - <> - {description ? ( - - ) : null} - - + ); }