@gitbook/react-openapi 1.2.1 → 1.3.1

package/src/code-samples.ts

@@ -30,7 +30,7 @@ export const codeSampleGenerators: CodeSampleGenerator[] = [
     {
         id: 'http',
         label: 'HTTP',
-        syntax: 'bash',
+        syntax: 'http',
         generate: ({ method, url, headers = {}, body }: CodeSampleInput) => {
             const { host, path } = parseHostAndPath(url);
 
@@ -356,18 +356,25 @@ const BodyGenerators = {
             // Convert JSON to XML if needed
             body = JSON.stringify(convertBodyToXML(body));
         } else {
-            body = stringifyOpenAPI(body, (_key, value) => {
-                switch (value) {
-                    case true:
-                        return '$$__TRUE__$$';
-                    case false:
-                        return '$$__FALSE__$$';
-                    default:
-                        return value;
-                }
-            })
+            body = stringifyOpenAPI(
+                body,
+                (_key, value) => {
+                    switch (value) {
+                        case true:
+                            return '$$__TRUE__$$';
+                        case false:
+                            return '$$__FALSE__$$';
+                        case null:
+                            return '$$__NULL__$$';
+                        default:
+                            return value;
+                    }
+                },
+                2
+            )
                 .replaceAll('"$$__TRUE__$$"', 'True')
-                .replaceAll('"$$__FALSE__$$"', 'False');
+                .replaceAll('"$$__FALSE__$$"', 'False')
+                .replaceAll('"$$__NULL__$$"', 'None');
         }
 
         return { body, code, headers };

package/src/generateSchemaExample.test.ts

@@ -1017,4 +1017,24 @@ describe('generateSchemaExample', () => {
             },
         });
     });
+
+    it('handles deprecated properties', () => {
+        expect(
+            generateSchemaExample({
+                type: 'object',
+                deprecated: true,
+            })
+        ).toBeUndefined();
+    });
+
+    it('handle nested deprecated properties', () => {
+        expect(
+            generateSchemaExample({
+                type: 'array',
+                items: {
+                    deprecated: true,
+                },
+            })
+        ).toBeUndefined();
+    });
 });

package/src/generateSchemaExample.ts

@@ -167,7 +167,7 @@ const getExampleFromSchema = (
     const makeUpRandomData = !!options?.emptyString;
 
     // If the property is deprecated we don't show it in examples.
-    if (schema.deprecated) {
+    if (schema.deprecated || (schema.type === 'array' && schema.items?.deprecated)) {
         return undefined;
     }
 
@@ -204,6 +204,14 @@ const getExampleFromSchema = (
         return cache(schema, schema.example);
     }
 
+    // Use a default value, if there’s one and it’s a string or number
+    if (
+        schema.default !== undefined &&
+        ['string', 'number', 'boolean'].includes(typeof schema.default)
+    ) {
+        return cache(schema, schema.default);
+    }
+
     // enum: [ 'available', 'pending', 'sold' ]
     if (Array.isArray(schema.enum) && schema.enum.length > 0) {
         return cache(schema, schema.enum[0]);

package/src/getDisclosureLabel.ts

@@ -0,0 +1,25 @@
+'use client';
+
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import type { OpenAPIClientContext } from './context';
+import { tString } from './translate';
+
+export function getDisclosureLabel(props: {
+    schema: OpenAPIV3.SchemaObject;
+    isExpanded: boolean;
+    context: OpenAPIClientContext;
+}) {
+    const { schema, isExpanded, context } = props;
+    let label: string;
+    if (schema.type === 'array' && !!schema.items) {
+        if (schema.items.oneOf) {
+            label = tString(context.translation, 'available_items').toLowerCase();
+        } else {
+            label = tString(context.translation, 'properties').toLowerCase();
+        }
+    } else {
+        label = tString(context.translation, 'properties').toLowerCase();
+    }
+
+    return tString(context.translation, isExpanded ? 'hide' : 'show', label);
+}

package/src/schemas/OpenAPISchemaItem.tsx

@@ -0,0 +1,34 @@
+'use client';
+
+import { SectionBody } from '../StaticSection';
+
+import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import { OpenAPIDisclosure } from '../OpenAPIDisclosure';
+import { OpenAPIRootSchema } from '../OpenAPISchemaServer';
+import { Section } from '../StaticSection';
+import type { OpenAPIClientContext } from '../context';
+import { getDisclosureLabel } from '../getDisclosureLabel';
+
+export function OpenAPISchemaItem(props: {
+    name: string;
+    schema: OpenAPIV3.SchemaObject;
+    context: OpenAPIClientContext;
+}) {
+    const { schema, context, name } = props;
+
+    return (
+        <OpenAPIDisclosure
+            className="openapi-schemas-disclosure"
+            key={name}
+            icon={context.icons.plus}
+            header={name}
+            label={(isExpanded) => getDisclosureLabel({ schema, isExpanded, context })}
+        >
+            <Section className="openapi-section-schemas">
+                <SectionBody>
+                    <OpenAPIRootSchema schema={schema} context={context} />
+                </SectionBody>
+            </Section>
+        </OpenAPIDisclosure>
+    );
+}

package/src/schemas/OpenAPISchemas.tsx

@@ -1,9 +1,8 @@
 import type { OpenAPISchema } from '@gitbook/openapi-parser';
 import clsx from 'clsx';
-import { OpenAPIDisclosure } from '../OpenAPIDisclosure';
 import { OpenAPIExample } from '../OpenAPIExample';
 import { OpenAPIRootSchema } from '../OpenAPISchemaServer';
-import { Section, SectionBody, StaticSection } from '../StaticSection';
+import { StaticSection } from '../StaticSection';
 import {
     type OpenAPIContextInput,
     getOpenAPIClientContext,
@@ -11,6 +10,7 @@ import {
 } from '../context';
 import { t } from '../translate';
 import { getExampleFromSchema } from '../util/example';
+import { OpenAPISchemaItem } from './OpenAPISchemaItem';
 
 /**
  * OpenAPI Schemas component.
@@ -85,18 +85,12 @@ export function OpenAPISchemas(props: {
         <div className={clsx('openapi-schemas', className)}>
             {schemas.map(({ name, schema }) => {
                 return (
-                    <OpenAPIDisclosure
-                        className="openapi-schemas-disclosure"
+                    <OpenAPISchemaItem
                         key={name}
-                        icon={context.icons.chevronRight}
-                        label={name}
-                    >
-                        <Section className="openapi-section-schemas">
-                            <SectionBody>
-                                <OpenAPIRootSchema schema={schema} context={clientContext} />
-                            </SectionBody>
-                        </Section>
-                    </OpenAPIDisclosure>
+                        name={name}
+                        context={clientContext}
+                        schema={schema}
+                    />
                 );
             })}
         </div>

package/src/translations/de.ts

@@ -18,9 +18,11 @@ export const de = {
     nullable: 'Nullfähig',
     body: 'Rumpf',
     payload: 'Nutzlast',
-    headers: 'Kopfzeilen',
+    headers: 'Header',
+    header: 'Header',
     authorizations: 'Autorisierungen',
     responses: 'Antworten',
+    response: 'Antwort',
     path_parameters: 'Pfadparameter',
     query_parameters: 'Abfrageparameter',
     header_parameters: 'Header-Parameter',
@@ -30,8 +32,12 @@ export const de = {
     success: 'Erfolg',
     redirect: 'Umleitung',
     error: 'Fehler',
-    show: 'Anzeigen',
-    hide: 'Verstecken',
+    show: 'Zeige ${1}',
+    hide: 'Verstecke ${1}',
     available_items: 'Verfügbare Elemente',
-    child_attributes: 'Unterattribute',
+    available_scopes: 'Verfügbare scopes',
+    properties: 'Eigenschaften',
+    or: 'oder',
+    and: 'und',
+    possible_values: 'Mögliche Werte',
 };

package/src/translations/en.ts

@@ -19,8 +19,10 @@ export const en = {
     body: 'Body',
     payload: 'Payload',
     headers: 'Headers',
+    header: 'Header',
     authorizations: 'Authorizations',
     responses: 'Responses',
+    response: 'Response',
     path_parameters: 'Path parameters',
     query_parameters: 'Query parameters',
     header_parameters: 'Header parameters',
@@ -30,8 +32,12 @@ export const en = {
     success: 'Success',
     redirect: 'Redirect',
     error: 'Error',
-    show: 'Show',
-    hide: 'Hide',
+    show: 'Show ${1}',
+    hide: 'Hide ${1}',
     available_items: 'Available items',
-    child_attributes: 'Child attributes',
+    available_scopes: 'Available scopes',
+    possible_values: 'Possible values',
+    properties: 'Properties',
+    or: 'or',
+    and: 'and',
 };

package/src/translations/es.ts

@@ -18,9 +18,11 @@ export const es = {
     nullable: 'Nulo',
     body: 'Cuerpo',
     payload: 'Caga útil',
-    headers: 'Encabezados',
+    headers: 'Headers',
+    header: 'Header',
     authorizations: 'Autorizaciones',
     responses: 'Respuestas',
+    response: 'Respuesta',
     path_parameters: 'Parámetros de ruta',
     query_parameters: 'Parámetros de consulta',
     header_parameters: 'Parámetros de encabezado',
@@ -30,8 +32,12 @@ export const es = {
     success: 'Éxito',
     redirect: 'Redirección',
     error: 'Error',
-    show: 'Mostrar',
-    hide: 'Ocultar',
+    show: 'Mostrar ${1}',
+    hide: 'Ocultar ${1}',
     available_items: 'Elementos disponibles',
-    child_attributes: 'Atributos secundarios',
+    available_scopes: 'Scopes disponibles',
+    properties: 'Propiedades',
+    or: 'o',
+    and: 'y',
+    possible_values: 'Valores posibles',
 };

package/src/translations/fr.ts

@@ -18,20 +18,26 @@ export const fr = {
     nullable: 'Nullable',
     body: 'Corps',
     payload: 'Charge utile',
-    headers: 'En-têtes',
+    headers: 'Headers',
+    header: 'Header',
     authorizations: 'Autorisations',
     responses: 'Réponses',
+    response: 'Réponse',
     path_parameters: 'Paramètres de chemin',
     query_parameters: 'Paramètres de requête',
-    header_parameters: 'Paramètres d’en-tête',
+    header_parameters: "Paramètres d'en-tête",
     attributes: 'Attributs',
     test_it: 'Tester',
     information: 'Information',
     success: 'Succès',
     redirect: 'Redirection',
     error: 'Erreur',
-    show: 'Afficher',
-    hide: 'Masquer',
+    show: 'Afficher ${1}',
+    hide: 'Masquer ${1}',
     available_items: 'Éléments disponibles',
-    child_attributes: 'Attributs enfants',
+    available_scopes: 'Scopes disponibles',
+    properties: 'Propriétés',
+    or: 'ou',
+    and: 'et',
+    possible_values: 'Valeurs possibles',
 };

package/src/translations/ja.ts

@@ -19,8 +19,10 @@ export const ja = {
     body: '本文',
     payload: 'ペイロード',
     headers: 'ヘッダー',
+    header: 'ヘッダー',
     authorizations: '認可',
     responses: 'レスポンス',
+    response: 'レスポンス',
     path_parameters: 'パスパラメータ',
     query_parameters: 'クエリパラメータ',
     header_parameters: 'ヘッダーパラメータ',
@@ -30,8 +32,12 @@ export const ja = {
     success: '成功',
     redirect: 'リダイレクト',
     error: 'エラー',
-    show: '表示',
-    hide: '非表示',
+    show: '${1}を表示',
+    hide: '${1}を非表示',
     available_items: '利用可能なアイテム',
-    child_attributes: '子属性',
+    available_scopes: '利用可能なスコープ',
+    properties: 'プロパティ',
+    or: 'または',
+    and: 'かつ',
+    possible_values: '可能な値',
 };

package/src/translations/nl.ts

@@ -19,8 +19,10 @@ export const nl = {
     body: 'Body',
     payload: 'Payload',
     headers: 'Headers',
+    header: 'Header',
     authorizations: 'Autorisaties',
     responses: 'Reacties',
+    response: 'Reactie',
     path_parameters: 'Padparameters',
     query_parameters: 'Queryparameters',
     header_parameters: 'Headerparameters',
@@ -30,8 +32,12 @@ export const nl = {
     success: 'Succes',
     redirect: 'Omleiding',
     error: 'Fout',
-    show: 'Toon',
-    hide: 'Verbergen',
+    show: 'Toon ${1}',
+    hide: 'Verberg ${1}',
     available_items: 'Beschikbare items',
-    child_attributes: 'Kindattributen',
+    available_scopes: 'Beschikbare scopes',
+    properties: 'Eigenschappen',
+    or: 'of',
+    and: 'en',
+    possible_values: 'Mogelijke waarden',
 };

package/src/translations/no.ts

@@ -18,9 +18,11 @@ export const no = {
     nullable: 'Kan være null',
     body: 'Brødtekst',
     payload: 'Nyttelast',
-    headers: 'Overskrifter',
+    headers: 'Headers',
+    header: 'Header',
     authorizations: 'Autorisasjoner',
     responses: 'Responser',
+    response: 'Respons',
     path_parameters: 'Sti-parametere',
     query_parameters: 'Forespørselsparametere',
     header_parameters: 'Header-parametere',
@@ -30,8 +32,12 @@ export const no = {
     success: 'Suksess',
     redirect: 'Viderekobling',
     error: 'Feil',
-    show: 'Vis',
-    hide: 'Skjul',
+    show: 'Vis ${1}',
+    hide: 'Skjul ${1}',
     available_items: 'Tilgjengelige elementer',
-    child_attributes: 'Barneattributter',
+    available_scopes: 'Tilgjengelige scopes',
+    properties: 'Egenskaper',
+    or: 'eller',
+    and: 'og',
+    possible_values: 'Mulige verdier',
 };

package/src/translations/pt-br.ts

@@ -18,9 +18,11 @@ export const pt_br = {
     nullable: 'Nulo',
     body: 'Corpo',
     payload: 'Carga útil',
-    headers: 'Cabeçalhos',
+    headers: 'Headers',
+    header: 'Header',
     authorizations: 'Autorizações',
     responses: 'Respostas',
+    response: 'Resposta',
     path_parameters: 'Parâmetros de rota',
     query_parameters: 'Parâmetros de consulta',
     header_parameters: 'Parâmetros de cabeçalho',
@@ -30,8 +32,12 @@ export const pt_br = {
     success: 'Sucesso',
     redirect: 'Redirecionamento',
     error: 'Erro',
-    show: 'Mostrar',
-    hide: 'Ocultar',
+    show: 'Mostrar ${1}',
+    hide: 'Ocultar ${1}',
     available_items: 'Itens disponíveis',
-    child_attributes: 'Atributos filhos',
+    available_scopes: 'Scopes disponíveis',
+    properties: 'Propriedades',
+    or: 'ou',
+    and: 'e',
+    possible_values: 'Valores possíveis',
 };

package/src/translations/zh.ts

@@ -18,9 +18,11 @@ export const zh = {
     nullable: '可为 null',
     body: '请求体',
     payload: '有效载荷',
-    headers: '头部信息',
+    headers: '头字段',
+    header: '头部',
     authorizations: '授权',
     responses: '响应',
+    response: '响应',
     path_parameters: '路径参数',
     query_parameters: '查询参数',
     header_parameters: '头参数',
@@ -30,8 +32,12 @@ export const zh = {
     success: '成功',
     redirect: '重定向',
     error: '错误',
-    show: '显示',
-    hide: '隐藏',
+    show: '显示${1}',
+    hide: '隐藏${1}',
     available_items: '可用项',
-    child_attributes: '子属性',
+    available_scopes: '可用范围',
+    properties: '属性',
+    or: '或',
+    and: '和',
+    possible_values: '可能的值',
 };

package/src/utils.ts

@@ -216,3 +216,40 @@ function getStatusCodeCategory(statusCode: number | string): number | string {
 
     return category;
 }
+
+export function getSchemaTitle(schema: OpenAPIV3.SchemaObject): string {
+    // Otherwise try to infer a nice title
+    let type = 'any';
+
+    if (schema.enum || schema['x-enumDescriptions'] || schema['x-gitbook-enum']) {
+        type = `${schema.type} · enum`;
+        // check array AND schema.items as this is sometimes null despite what the type indicates
+    } else if (schema.type === 'array' && !!schema.items) {
+        type = `${getSchemaTitle(schema.items)}[]`;
+    } else if (Array.isArray(schema.type)) {
+        type = schema.type.join(' | ');
+    } else if (schema.type || schema.properties) {
+        type = schema.type ?? 'object';
+
+        if (schema.format) {
+            type += ` · ${schema.format}`;
+        }
+
+        // Only add the title if it's an object (no need for the title of a string, number, etc.)
+        if (type === 'object' && schema.title) {
+            type += ` · ${schema.title.replaceAll(' ', '')}`;
+        }
+    }
+
+    if ('anyOf' in schema) {
+        type = 'any of';
+    } else if ('oneOf' in schema) {
+        type = 'one of';
+    } else if ('allOf' in schema) {
+        type = 'all of';
+    } else if ('not' in schema) {
+        type = 'not';
+    }
+
+    return type;
+}