@gitbook/react-openapi 1.1.9 → 1.2.0

package/src/generateSchemaExample.ts

@@ -166,6 +166,11 @@ const getExampleFromSchema = (
     // But if `emptyString` is  set, we do want to see some values.
     const makeUpRandomData = !!options?.emptyString;
 
+    // If the property is deprecated we don't show it in examples.
+    if (schema.deprecated) {
+        return undefined;
+    }
+
     // Check if the property is read-only/write-only
     if (
         (options?.mode === 'write' && schema.readOnly) ||

package/src/getOrCreateStoreByKey.ts

@@ -0,0 +1,33 @@
+import { createStore } from 'zustand';
+
+type Key = string | number;
+
+type State = {
+    key: Key | null;
+};
+
+type Actions = { setKey: (key: Key | null) => void };
+
+export type Store = State & Actions;
+
+const createStateStore = (initial?: Key) => {
+    return createStore<Store>()((set) => ({
+        key: initial ?? null,
+        setKey: (key) => {
+            set(() => ({ key }));
+        },
+    }));
+};
+
+const defaultStores = new Map<string, ReturnType<typeof createStateStore>>();
+
+const createStateStoreFactory = (stores: typeof defaultStores) => {
+    return (storeKey: string, initialKey?: Key) => {
+        if (!stores.has(storeKey)) {
+            stores.set(storeKey, createStateStore(initialKey));
+        }
+        return stores.get(storeKey)!;
+    };
+};
+
+export const getOrCreateStoreByKey = createStateStoreFactory(defaultStores);

package/src/index.ts

@@ -1,5 +1,9 @@
 export * from './schemas';
 export * from './OpenAPIOperation';
+export * from './OpenAPIWebhook';
 export * from './OpenAPIOperationContext';
 export * from './resolveOpenAPIOperation';
-export type { OpenAPISchemasData, OpenAPIOperationData } from './types';
+export * from './resolveOpenAPIWebhook';
+export type { OpenAPIOperationData, OpenAPIWebhookData } from './types';
+export type { OpenAPIContextInput } from './context';
+export { checkIsValidLocale } from './translations';

package/src/resolveOpenAPIOperation.ts

@@ -40,16 +40,27 @@ export async function resolveOpenAPIOperation(
     }
 
     const servers = 'servers' in schema ? (schema.servers ?? []) : [];
-    const security = flattenSecurities(operation.security ?? schema.security ?? []);
+    const security: OpenAPIV3_1.SecurityRequirementObject[] =
+        operation.security ?? schema.security ?? [];
+
+    // If security includes an empty object, it means that the security is optional
+    const isOptionalSecurity = security.some((entry) => Object.keys(entry).length === 0);
+    const flatSecurities = flattenSecurities(security);
 
     // Resolve securities
     const securities: OpenAPIOperationData['securities'] = [];
-    for (const entry of security) {
+    for (const entry of flatSecurities) {
         const securityKey = Object.keys(entry)[0];
         if (securityKey) {
             const securityScheme = schema.components?.securitySchemes?.[securityKey];
             if (securityScheme && !checkIsReference(securityScheme)) {
-                securities.push([securityKey, securityScheme]);
+                securities.push([
+                    securityKey,
+                    {
+                        ...securityScheme,
+                        required: !isOptionalSecurity,
+                    },
+                ]);
             }
         }
     }

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,99 +1,104 @@
+import type { OpenAPISchema } from '@gitbook/openapi-parser';
 import clsx from 'clsx';
-import { OpenAPIDisclosureGroup } from '../OpenAPIDisclosureGroup';
+import { OpenAPIDisclosure } from '../OpenAPIDisclosure';
+import { OpenAPIExample } from '../OpenAPIExample';
 import { OpenAPIRootSchema } from '../OpenAPISchemaServer';
-import { Section, SectionBody } from '../StaticSection';
-import type { OpenAPIClientContext, OpenAPIContextProps, OpenAPISchemasData } from '../types';
-
-type OpenAPISchemasContextProps = Omit<
-    OpenAPIContextProps,
-    'renderCodeBlock' | 'renderHeading' | 'renderDocument'
->;
+import { Section, SectionBody, StaticSection } from '../StaticSection';
+import {
+    type OpenAPIContextInput,
+    getOpenAPIClientContext,
+    resolveOpenAPIContext,
+} from '../context';
+import { t } from '../translate';
+import { getExampleFromSchema } from '../util/example';
 
 /**
- * Display OpenAPI Schemas.
+ * OpenAPI Schemas component.
  */
 export function OpenAPISchemas(props: {
     className?: string;
-    data: OpenAPISchemasData;
-    context: OpenAPISchemasContextProps;
+    schemas: OpenAPISchema[];
+    context: OpenAPIContextInput;
     /**
      * Whether to show the schema directly if there is only one.
      */
     grouped?: boolean;
 }) {
-    const { className, data, context, grouped } = props;
-    const { schemas } = data;
+    const { schemas, context: contextInput, grouped, className } = props;
 
-    const clientContext: OpenAPIClientContext = {
-        defaultInteractiveOpened: context.defaultInteractiveOpened,
-        icons: context.icons,
-        blockKey: context.blockKey,
-    };
+    const firstSchema = schemas[0];
 
-    if (!schemas.length) {
+    if (!firstSchema) {
         return null;
     }
 
-    return (
-        <div className={clsx('openapi-schemas', className)}>
-            <OpenAPIRootSchemasSchema grouped={grouped} schemas={schemas} context={clientContext} />
-        </div>
-    );
-}
-
-/**
- * Root schema for OpenAPI schemas.
- * It displays a single model or a disclosure group for multiple schemas.
- */
-function OpenAPIRootSchemasSchema(props: {
-    schemas: OpenAPISchemasData['schemas'];
-    context: OpenAPIClientContext;
-    grouped?: boolean;
-}) {
-    const { schemas, context, grouped } = props;
+    const context = resolveOpenAPIContext(contextInput);
+    const clientContext = getOpenAPIClientContext(context);
 
     // If there is only one model and we are not grouping, we show it directly.
     if (schemas.length === 1 && !grouped) {
-        const schema = schemas?.[0]?.schema;
-
-        if (!schema) {
-            return null;
-        }
-
+        const title = `The ${firstSchema.name} object`;
         return (
-            <Section>
-                <SectionBody>
-                    <OpenAPIRootSchema schema={schema} context={context} />
-                </SectionBody>
-            </Section>
+            <div className={clsx('openapi-schemas', className)}>
+                <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={t(context.translation, 'attributes')}
+                        >
+                            <OpenAPIRootSchema
+                                schema={firstSchema.schema}
+                                context={clientContext}
+                            />
+                        </StaticSection>
+                    </div>
+                    <div className="openapi-column-preview">
+                        <div className="openapi-column-preview-body">
+                            <div className="openapi-panel">
+                                <h4 className="openapi-panel-heading">{title}</h4>
+                                <div className="openapi-panel-body">
+                                    <OpenAPIExample
+                                        example={getExampleFromSchema({
+                                            schema: firstSchema.schema,
+                                        })}
+                                        context={context}
+                                        syntax="json"
+                                    />
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
         );
     }
 
     // If there are multiple schemas, we use a disclosure group to show them all.
     return (
-        <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={context} />
-                                </SectionBody>
-                            </Section>
-                        ),
-                    },
-                ],
-            }))}
-        />
+        <div className={clsx('openapi-schemas', className)}>
+            {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/schemas/resolveOpenAPISchemas.ts

@@ -1,9 +1,6 @@
-import type { Filesystem, OpenAPIV3xDocument } from '@gitbook/openapi-parser';
+import type { Filesystem, OpenAPISchema, OpenAPIV3xDocument } from '@gitbook/openapi-parser';
 import { filterSelectedOpenAPISchemas } from '@gitbook/openapi-parser';
 import { dereferenceFilesystem } from '../dereference';
-import type { OpenAPISchemasData } from '../types';
-
-//!!TODO: We should return only the schemas that are used in the block. Still a WIP awaiting future work.
 
 /**
  * Resolve an OpenAPI schemas from a file and compile it to a more usable format.
@@ -14,7 +11,9 @@ export async function resolveOpenAPISchemas(
     options: {
         schemas: string[];
     }
-): Promise<OpenAPISchemasData | null> {
+): Promise<{
+    schemas: OpenAPISchema[];
+} | null> {
     const { schemas: selectedSchemas } = options;
 
     const schema = await dereferenceFilesystem(filesystem);

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',
+};