@gitbook/react-openapi 1.1.10 → 1.2.1

package/src/resolveOpenAPIWebhook.ts

@@ -0,0 +1,99 @@
+import { fromJSON, toJSON } from 'flatted';
+
+import type {
+    Filesystem,
+    OpenAPIV3,
+    OpenAPIV3_1,
+    OpenAPIV3xDocument,
+} from '@gitbook/openapi-parser';
+import { dereferenceFilesystem } from './dereference';
+import type { OpenAPIWebhookData } from './types';
+
+export { fromJSON, toJSON };
+
+/**
+ * Resolve an OpenAPI webhook in a file and compile it to a more usable format.
+ */
+export async function resolveOpenAPIWebhook(
+    filesystem: Filesystem<OpenAPIV3xDocument>,
+    webhookDescriptor: {
+        name: string;
+        method: string;
+    }
+): Promise<OpenAPIWebhookData | null> {
+    const { name, method } = webhookDescriptor;
+    const schema = await dereferenceFilesystem(filesystem);
+    let operation = getWebhookByNameAndMethod(schema, name, method);
+
+    if (!operation) {
+        return null;
+    }
+
+    // Resolve common parameters
+    const commonParameters = getPathObjectParameter(schema, name);
+    if (commonParameters) {
+        operation = {
+            ...operation,
+            parameters: [...commonParameters, ...(operation.parameters ?? [])],
+        };
+    }
+
+    const servers = 'servers' in schema ? (schema.servers ?? []) : [];
+
+    return {
+        servers,
+        operation,
+        method,
+        name,
+    };
+}
+
+/**
+ * Get a path object from its path.
+ */
+function getPathObject(
+    schema: OpenAPIV3.Document | OpenAPIV3_1.Document,
+    name: string
+): OpenAPIV3.PathItemObject | OpenAPIV3_1.PathItemObject | null {
+    if (schema.webhooks?.[name]) {
+        return schema.webhooks[name];
+    }
+    return null;
+}
+
+/**
+ * Resolve parameters from a path in an OpenAPI schema.
+ */
+function getPathObjectParameter(
+    schema: OpenAPIV3.Document | OpenAPIV3_1.Document,
+    path: string
+):
+    | (OpenAPIV3.ReferenceObject | OpenAPIV3.ParameterObject)[]
+    | (OpenAPIV3.ParameterObject | OpenAPIV3_1.ReferenceObject)[]
+    | null {
+    const pathObject = getPathObject(schema, path);
+    if (pathObject?.parameters) {
+        return pathObject.parameters;
+    }
+    return null;
+}
+
+/**
+ * Get an operation by its path and method.
+ */
+function getWebhookByNameAndMethod(
+    schema: OpenAPIV3.Document | OpenAPIV3_1.Document,
+    name: string,
+    method: string
+): OpenAPIV3.OperationObject | null {
+    // Types are buffy for OpenAPIV3_1.OperationObject, so we use v3
+    const pathObject = getPathObject(schema, name);
+    if (!pathObject) {
+        return null;
+    }
+    const normalizedMethod = method.toLowerCase();
+    if (!pathObject[normalizedMethod]) {
+        return null;
+    }
+    return pathObject[normalizedMethod];
+}

package/src/schemas/OpenAPISchemas.tsx

@@ -1,11 +1,16 @@
 import type { OpenAPISchema } from '@gitbook/openapi-parser';
 import clsx from 'clsx';
-import { OpenAPIDisclosureGroup } from '../OpenAPIDisclosureGroup';
-import { OpenAPIExample, getExampleFromSchema } from '../OpenAPIExample';
+import { OpenAPIDisclosure } from '../OpenAPIDisclosure';
+import { OpenAPIExample } from '../OpenAPIExample';
 import { OpenAPIRootSchema } from '../OpenAPISchemaServer';
 import { Section, SectionBody, StaticSection } from '../StaticSection';
-import { getOpenAPIClientContext } from '../context';
-import type { OpenAPIContext } from '../types';
+import {
+    type OpenAPIContextInput,
+    getOpenAPIClientContext,
+    resolveOpenAPIContext,
+} from '../context';
+import { t } from '../translate';
+import { getExampleFromSchema } from '../util/example';
 
 /**
  * OpenAPI Schemas component.
@@ -13,13 +18,13 @@ import type { OpenAPIContext } from '../types';
 export function OpenAPISchemas(props: {
     className?: string;
     schemas: OpenAPISchema[];
-    context: OpenAPIContext;
+    context: OpenAPIContextInput;
     /**
      * Whether to show the schema directly if there is only one.
      */
     grouped?: boolean;
 }) {
-    const { schemas, context, grouped, className } = props;
+    const { schemas, context: contextInput, grouped, className } = props;
 
     const firstSchema = schemas[0];
 
@@ -27,6 +32,7 @@ export function OpenAPISchemas(props: {
         return null;
     }
 
+    const context = resolveOpenAPIContext(contextInput);
     const clientContext = getOpenAPIClientContext(context);
 
     // If there is only one model and we are not grouping, we show it directly.
@@ -37,11 +43,16 @@ export function OpenAPISchemas(props: {
                 <div className="openapi-summary" id={context.id}>
                     {context.renderHeading({
                         title,
+                        deprecated: Boolean(firstSchema.schema.deprecated),
+                        stability: firstSchema.schema['x-stability'],
                     })}
                 </div>
                 <div className="openapi-columns">
                     <div className="openapi-column-spec">
-                        <StaticSection className="openapi-parameters" header="Attributes">
+                        <StaticSection
+                            className="openapi-parameters"
+                            header={t(context.translation, 'attributes')}
+                        >
                             <OpenAPIRootSchema
                                 schema={firstSchema.schema}
                                 context={clientContext}
@@ -72,33 +83,22 @@ export function OpenAPISchemas(props: {
     // If there are multiple schemas, we use a disclosure group to show them all.
     return (
         <div className={clsx('openapi-schemas', className)}>
-            <OpenAPIDisclosureGroup
-                allowsMultipleExpanded
-                icon={context.icons.chevronRight}
-                groups={schemas.map(({ name, schema }) => ({
-                    id: name,
-                    label: (
-                        <div className="openapi-response-tab-content" key={`model-${name}`}>
-                            <span className="openapi-response-statuscode">{name}</span>
-                        </div>
-                    ),
-                    tabs: [
-                        {
-                            id: 'model',
-                            body: (
-                                <Section className="openapi-section-schemas">
-                                    <SectionBody>
-                                        <OpenAPIRootSchema
-                                            schema={schema}
-                                            context={clientContext}
-                                        />
-                                    </SectionBody>
-                                </Section>
-                            ),
-                        },
-                    ],
-                }))}
-            />
+            {schemas.map(({ name, schema }) => {
+                return (
+                    <OpenAPIDisclosure
+                        className="openapi-schemas-disclosure"
+                        key={name}
+                        icon={context.icons.chevronRight}
+                        label={name}
+                    >
+                        <Section className="openapi-section-schemas">
+                            <SectionBody>
+                                <OpenAPIRootSchema schema={schema} context={clientContext} />
+                            </SectionBody>
+                        </Section>
+                    </OpenAPIDisclosure>
+                );
+            })}
         </div>
     );
 }

package/src/stringifyOpenAPI.ts

@@ -1,17 +1,25 @@
 /**
  * Stringify an OpenAPI object. Same API as JSON.stringify.
  */
-export function stringifyOpenAPI(body: unknown, _?: null, indent?: number): string {
+export function stringifyOpenAPI(
+    value: any,
+    replacer?: ((this: any, key: string, value: any) => any) | null,
+    space?: string | number
+): string {
     return JSON.stringify(
-        body,
+        value,
         (key, value) => {
             // Ignore internal keys
             if (key.startsWith('x-gitbook-')) {
                 return undefined;
             }
 
+            if (replacer) {
+                return replacer(key, value);
+            }
+
             return value;
         },
-        indent
+        space
     );
 }

package/src/translate.tsx

@@ -0,0 +1,80 @@
+import React from 'react';
+
+import type { Translation, TranslationKey } from './translations';
+
+/**
+ * Translate a string.
+ */
+export function t(
+    translation: Translation,
+    id: TranslationKey,
+    ...args: React.ReactNode[]
+): React.ReactNode {
+    const string = translation[id];
+    if (!string) {
+        throw new Error(`Translation not found for "${id}"`);
+    }
+
+    // Now we are going to replace the arguments
+    // but we want to return a string as long as it's possible
+    // (eg. if there isn't any argument that is a ReactNode)
+    const parts: React.ReactNode[] = [];
+    let currentStringToReplace: string = string;
+
+    args.forEach((arg, i) => {
+        if (typeof arg === 'string') {
+            currentStringToReplace = currentStringToReplace.replace(`\${${i + 1}}`, arg);
+        } else {
+            const [partToPush, partToReplace] = currentStringToReplace.split(`\${${i + 1}}`);
+            if (partToPush === undefined || partToReplace === undefined) {
+                throw new Error(`Invalid translation "${id}"`);
+            }
+            parts.push(<React.Fragment key={`string-${i}`}>{partToPush}</React.Fragment>);
+            parts.push(<React.Fragment key={`arg-${i}`}>{arg}</React.Fragment>);
+            currentStringToReplace = partToReplace;
+        }
+    });
+
+    if (!parts.length) {
+        return currentStringToReplace;
+    }
+
+    return (
+        <>
+            {parts}
+            {currentStringToReplace}
+        </>
+    );
+}
+
+/**
+ * Version of `t` that returns a string.
+ */
+export function tString(
+    translation: Translation,
+    id: TranslationKey,
+    ...args: React.ReactNode[]
+): string {
+    const result = t(translation, id, ...args);
+    return reactToString(result);
+}
+
+function reactToString(el: React.ReactNode): string {
+    if (typeof el === 'string' || typeof el === 'number' || typeof el === 'boolean') {
+        return `${el}`;
+    }
+
+    if (el === null || el === undefined) {
+        return '';
+    }
+
+    if (Array.isArray(el)) {
+        return el.map(reactToString).join('');
+    }
+
+    if (typeof el === 'object' && 'props' in el) {
+        return el.props.children.map(reactToString).join('');
+    }
+
+    throw new Error(`Unsupported type ${typeof el}`);
+}

package/src/translations/de.ts

@@ -0,0 +1,37 @@
+export const de = {
+    required: 'Erforderlich',
+    deprecated: 'Veraltet',
+    deprecated_and_sunset_on: 'Diese Operation ist veraltet und wird am ${1} eingestellt.',
+    stability_experimental: 'Experimentell',
+    stability_alpha: 'Alpha',
+    stability_beta: 'Beta',
+    copy_to_clipboard: 'In die Zwischenablage kopieren',
+    copied: 'Kopiert',
+    no_content: 'Kein Inhalt',
+    unresolved_reference: 'Nicht aufgelöste Referenz',
+    circular_reference: 'Zirkuläre Referenz',
+    read_only: 'Nur lesen',
+    write_only: 'Nur schreiben',
+    optional: 'Optional',
+    min: 'Min',
+    max: 'Max',
+    nullable: 'Nullfähig',
+    body: 'Rumpf',
+    payload: 'Nutzlast',
+    headers: 'Kopfzeilen',
+    authorizations: 'Autorisierungen',
+    responses: 'Antworten',
+    path_parameters: 'Pfadparameter',
+    query_parameters: 'Abfrageparameter',
+    header_parameters: 'Header-Parameter',
+    attributes: 'Attribute',
+    test_it: 'Teste es',
+    information: 'Information',
+    success: 'Erfolg',
+    redirect: 'Umleitung',
+    error: 'Fehler',
+    show: 'Anzeigen',
+    hide: 'Verstecken',
+    available_items: 'Verfügbare Elemente',
+    child_attributes: 'Unterattribute',
+};

package/src/translations/en.ts

@@ -0,0 +1,37 @@
+export const en = {
+    required: 'Required',
+    deprecated: 'Deprecated',
+    deprecated_and_sunset_on: 'This operation is deprecated and will be sunset on ${1}.',
+    stability_experimental: 'Experimental',
+    stability_alpha: 'Alpha',
+    stability_beta: 'Beta',
+    copy_to_clipboard: 'Copy to clipboard',
+    copied: 'Copied',
+    no_content: 'No content',
+    unresolved_reference: 'Unresolved reference',
+    circular_reference: 'Circular reference',
+    read_only: 'Read-only',
+    write_only: 'Write-only',
+    optional: 'Optional',
+    min: 'Min',
+    max: 'Max',
+    nullable: 'Nullable',
+    body: 'Body',
+    payload: 'Payload',
+    headers: 'Headers',
+    authorizations: 'Authorizations',
+    responses: 'Responses',
+    path_parameters: 'Path parameters',
+    query_parameters: 'Query parameters',
+    header_parameters: 'Header parameters',
+    attributes: 'Attributes',
+    test_it: 'Test it',
+    information: 'Information',
+    success: 'Success',
+    redirect: 'Redirect',
+    error: 'Error',
+    show: 'Show',
+    hide: 'Hide',
+    available_items: 'Available items',
+    child_attributes: 'Child attributes',
+};

package/src/translations/es.ts

@@ -0,0 +1,37 @@
+export const es = {
+    required: 'Requerido',
+    deprecated: 'Obsoleto',
+    deprecated_and_sunset_on: 'Esta operación está obsoleta y se retirará el ${1}.',
+    stability_experimental: 'Experimental',
+    stability_alpha: 'Alfa',
+    stability_beta: 'Beta',
+    copy_to_clipboard: 'Copiar al portapapeles',
+    copied: 'Copiado',
+    no_content: 'Sin contenido',
+    unresolved_reference: 'Referencia no resuelta',
+    circular_reference: 'Referencia circular',
+    read_only: 'Solo lectura',
+    write_only: 'Solo escritura',
+    optional: 'Opcional',
+    min: 'Mín',
+    max: 'Máx',
+    nullable: 'Nulo',
+    body: 'Cuerpo',
+    payload: 'Caga útil',
+    headers: 'Encabezados',
+    authorizations: 'Autorizaciones',
+    responses: 'Respuestas',
+    path_parameters: 'Parámetros de ruta',
+    query_parameters: 'Parámetros de consulta',
+    header_parameters: 'Parámetros de encabezado',
+    attributes: 'Atributos',
+    test_it: 'Pruébalo',
+    information: 'Información',
+    success: 'Éxito',
+    redirect: 'Redirección',
+    error: 'Error',
+    show: 'Mostrar',
+    hide: 'Ocultar',
+    available_items: 'Elementos disponibles',
+    child_attributes: 'Atributos secundarios',
+};

package/src/translations/fr.ts

@@ -0,0 +1,37 @@
+export const fr = {
+    required: 'Requis',
+    deprecated: 'Obsolète',
+    deprecated_and_sunset_on: 'Cette opération est obsolète et sera supprimée le ${1}.',
+    stability_experimental: 'Expérimental',
+    stability_alpha: 'Alpha',
+    stability_beta: 'Bêta',
+    copy_to_clipboard: 'Copier dans le presse-papiers',
+    copied: 'Copié',
+    no_content: 'Aucun contenu',
+    unresolved_reference: 'Référence non résolue',
+    circular_reference: 'Référence circulaire',
+    read_only: 'Lecture seule',
+    write_only: 'Écriture seule',
+    optional: 'Optionnel',
+    min: 'Min',
+    max: 'Max',
+    nullable: 'Nullable',
+    body: 'Corps',
+    payload: 'Charge utile',
+    headers: 'En-têtes',
+    authorizations: 'Autorisations',
+    responses: 'Réponses',
+    path_parameters: 'Paramètres de chemin',
+    query_parameters: 'Paramètres de requê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',
+    available_items: 'Éléments disponibles',
+    child_attributes: 'Attributs enfants',
+};

package/src/translations/index.ts

@@ -0,0 +1,33 @@
+import { de } from './de';
+import { en } from './en';
+import { es } from './es';
+import { fr } from './fr';
+import { ja } from './ja';
+import { nl } from './nl';
+import { no } from './no';
+import { pt_br } from './pt-br';
+import type { Translation } from './types';
+import { zh } from './zh';
+
+export * from './types';
+
+export const translations = {
+    en,
+    de,
+    es,
+    fr,
+    ja,
+    nl,
+    no,
+    'pt-br': pt_br,
+    zh,
+} satisfies Record<string, Translation>;
+
+export type TranslationLocale = keyof typeof translations;
+
+/**
+ * Check if the locale is valid.
+ */
+export function checkIsValidLocale(locale: string): locale is TranslationLocale {
+    return Object.prototype.hasOwnProperty.call(translations, locale);
+}

package/src/translations/ja.ts

@@ -0,0 +1,37 @@
+export const ja = {
+    required: '必須',
+    deprecated: '非推奨',
+    deprecated_and_sunset_on: 'この操作は非推奨であり、${1}に廃止されます。',
+    stability_experimental: '実験的',
+    stability_alpha: 'アルファ',
+    stability_beta: 'ベータ',
+    copy_to_clipboard: 'クリップボードにコピー',
+    copied: 'コピー済み',
+    no_content: 'コンテンツなし',
+    unresolved_reference: '未解決の参照',
+    circular_reference: '循環参照',
+    read_only: '読み取り専用',
+    write_only: '書き込み専用',
+    optional: 'オプション',
+    min: '最小',
+    max: '最大',
+    nullable: 'ヌル許容',
+    body: '本文',
+    payload: 'ペイロード',
+    headers: 'ヘッダー',
+    authorizations: '認可',
+    responses: 'レスポンス',
+    path_parameters: 'パスパラメータ',
+    query_parameters: 'クエリパラメータ',
+    header_parameters: 'ヘッダーパラメータ',
+    attributes: '属性',
+    test_it: 'テストする',
+    information: '情報',
+    success: '成功',
+    redirect: 'リダイレクト',
+    error: 'エラー',
+    show: '表示',
+    hide: '非表示',
+    available_items: '利用可能なアイテム',
+    child_attributes: '子属性',
+};

package/src/translations/nl.ts

@@ -0,0 +1,37 @@
+export const nl = {
+    required: 'Vereist',
+    deprecated: 'Verouderd',
+    deprecated_and_sunset_on: 'Deze bewerking is verouderd en wordt op ${1} beëindigd.',
+    stability_experimental: 'Experimenteel',
+    stability_alpha: 'Alfa',
+    stability_beta: 'Bèta',
+    copy_to_clipboard: 'Kopiëren naar klembord',
+    copied: 'Gekopieerd',
+    no_content: 'Geen inhoud',
+    unresolved_reference: 'Onopgeloste verwijzing',
+    circular_reference: 'Circulaire verwijzing',
+    read_only: 'Alleen lezen',
+    write_only: 'Alleen schrijven',
+    optional: 'Optioneel',
+    min: 'Min',
+    max: 'Max',
+    nullable: 'Null toegestaan',
+    body: 'Body',
+    payload: 'Payload',
+    headers: 'Headers',
+    authorizations: 'Autorisaties',
+    responses: 'Reacties',
+    path_parameters: 'Padparameters',
+    query_parameters: 'Queryparameters',
+    header_parameters: 'Headerparameters',
+    attributes: 'Attributen',
+    test_it: 'Test het',
+    information: 'Informatie',
+    success: 'Succes',
+    redirect: 'Omleiding',
+    error: 'Fout',
+    show: 'Toon',
+    hide: 'Verbergen',
+    available_items: 'Beschikbare items',
+    child_attributes: 'Kindattributen',
+};

package/src/translations/no.ts

@@ -0,0 +1,37 @@
+export const no = {
+    required: 'Påkrevd',
+    deprecated: 'Foreldet',
+    deprecated_and_sunset_on: 'Denne operasjonen er foreldet og vil bli avviklet den ${1}.',
+    stability_experimental: 'Eksperimentell',
+    stability_alpha: 'Alfa',
+    stability_beta: 'Beta',
+    copy_to_clipboard: 'Kopier til utklippstavle',
+    copied: 'Kopiert',
+    no_content: 'Ingen innhold',
+    unresolved_reference: 'Uavklart referanse',
+    circular_reference: 'Sirkulær referanse',
+    read_only: 'Skrivebeskyttet',
+    write_only: 'Kun skriving',
+    optional: 'Valgfri',
+    min: 'Min',
+    max: 'Maks',
+    nullable: 'Kan være null',
+    body: 'Brødtekst',
+    payload: 'Nyttelast',
+    headers: 'Overskrifter',
+    authorizations: 'Autorisasjoner',
+    responses: 'Responser',
+    path_parameters: 'Sti-parametere',
+    query_parameters: 'Forespørselsparametere',
+    header_parameters: 'Header-parametere',
+    attributes: 'Attributter',
+    test_it: 'Test det',
+    information: 'Informasjon',
+    success: 'Suksess',
+    redirect: 'Viderekobling',
+    error: 'Feil',
+    show: 'Vis',
+    hide: 'Skjul',
+    available_items: 'Tilgjengelige elementer',
+    child_attributes: 'Barneattributter',
+};

package/src/translations/pt-br.ts

@@ -0,0 +1,37 @@
+export const pt_br = {
+    required: 'Obrigatório',
+    deprecated: 'Obsoleto',
+    deprecated_and_sunset_on: 'Esta operação está obsoleta e será descontinuada em ${1}.',
+    stability_experimental: 'Experimental',
+    stability_alpha: 'Alfa',
+    stability_beta: 'Beta',
+    copy_to_clipboard: 'Copiar para a área de transferência',
+    copied: 'Copiado',
+    no_content: 'Sem conteúdo',
+    unresolved_reference: 'Referência não resolvida',
+    circular_reference: 'Referência circular',
+    read_only: 'Somente leitura',
+    write_only: 'Somente escrita',
+    optional: 'Opcional',
+    min: 'Mín',
+    max: 'Máx',
+    nullable: 'Nulo',
+    body: 'Corpo',
+    payload: 'Carga útil',
+    headers: 'Cabeçalhos',
+    authorizations: 'Autorizações',
+    responses: 'Respostas',
+    path_parameters: 'Parâmetros de rota',
+    query_parameters: 'Parâmetros de consulta',
+    header_parameters: 'Parâmetros de cabeçalho',
+    attributes: 'Atributos',
+    test_it: 'Testar',
+    information: 'Informação',
+    success: 'Sucesso',
+    redirect: 'Redirecionamento',
+    error: 'Erro',
+    show: 'Mostrar',
+    hide: 'Ocultar',
+    available_items: 'Itens disponíveis',
+    child_attributes: 'Atributos filhos',
+};

package/src/translations/types.ts

@@ -0,0 +1,7 @@
+import type { en } from './en';
+
+export type TranslationKey = keyof typeof en;
+
+export type Translation = {
+    [key in TranslationKey]: string;
+};