@gitbook/react-openapi 0.2.0

package/src/OpenAPISchema.tsx

@@ -0,0 +1,401 @@
+import classNames from 'classnames';
+import { OpenAPIV3 } from 'openapi-types';
+import React, { useId } from 'react';
+
+import { InteractiveSection } from './InteractiveSection';
+import { Markdown } from './Markdown';
+import { SYMBOL_REF_RESOLVED } from './resolveOpenAPIPath';
+import { OpenAPIClientContext } from './types';
+import { noReference } from './utils';
+
+type CircularRefsIds = Map<OpenAPIV3.SchemaObject, string>;
+
+interface OpenAPISchemaPropertyEntry {
+    propertyName?: string;
+    required?: boolean;
+    schema: OpenAPIV3.SchemaObject;
+}
+
+/**
+ * Render a property of an OpenAPI schema.
+ */
+export function OpenAPISchemaProperty(
+    props: OpenAPISchemaPropertyEntry & {
+        /** Set of objects already observed as parents */
+        circularRefs?: CircularRefsIds;
+        context: OpenAPIClientContext;
+        className?: string;
+    },
+) {
+    const {
+        propertyName,
+        required,
+        schema,
+        circularRefs: parentCircularRefs = new Map<OpenAPIV3.SchemaObject, string>(),
+        context,
+        className,
+    } = props;
+
+    const id = useId();
+
+    const parentCircularRef = parentCircularRefs.get(schema);
+    const circularRefs = new Map(parentCircularRefs).set(schema, id);
+
+    // Avoid recursing infinitely, and instead render a link to the parent schema
+    const properties = parentCircularRef ? null : getSchemaProperties(schema);
+    const alternatives = parentCircularRef
+        ? null
+        : getSchemaAlternatives(schema, new Set(circularRefs.keys()));
+
+    const shouldDisplayExample = (schema: OpenAPIV3.SchemaObject): boolean => {
+        return (
+            typeof schema.example === 'string' ||
+            typeof schema.example === 'number' ||
+            typeof schema.example === 'boolean'
+        );
+    };
+    return (
+        <InteractiveSection
+            id={id}
+            className={classNames('openapi-schema', className)}
+            toggeable={!!properties || !!alternatives}
+            defaultOpened={!!context.defaultInteractiveOpened}
+            toggleOpenIcon={context.icons.chevronRight}
+            toggleCloseIcon={context.icons.chevronDown}
+            tabs={alternatives?.[0].map((alternative, index) => ({
+                key: `${index}`,
+                label: getSchemaTitle(alternative, alternatives[1]),
+                body: circularRefs.has(alternative) ? (
+                    <OpenAPISchemaCircularRef
+                        id={circularRefs.get(alternative)!}
+                        schema={alternative}
+                    />
+                ) : (
+                    <OpenAPISchemaAlternative
+                        schema={alternative}
+                        circularRefs={circularRefs}
+                        context={context}
+                    />
+                ),
+            }))}
+            header={
+                <div className={classNames('openapi-schema-presentation')}>
+                    <div className={classNames('openapi-schema-name')}>
+                        {propertyName ? (
+                            <span className={classNames('openapi-schema-propertyname')}>
+                                {propertyName}
+                            </span>
+                        ) : null}
+                        {required ? (
+                            <span className={classNames('openapi-schema-required')}>*</span>
+                        ) : null}
+                        <span className={classNames('openapi-schema-type')}>
+                            {getSchemaTitle(schema)}
+                        </span>
+                    </div>
+                    {schema.description ? (
+                        <Markdown
+                            source={schema.description}
+                            className="openapi-schema-description"
+                        />
+                    ) : null}
+                    {shouldDisplayExample(schema) ? (
+                        <span className="openapi-schema-example">
+                            Example: <code>{JSON.stringify(schema.example)}</code>
+                        </span>
+                    ) : null}
+                </div>
+            }
+        >
+            {(properties && properties.length > 0) ||
+            (schema.enum && schema.enum.length > 0) ||
+            parentCircularRef ? (
+                <>
+                    {properties?.length ? (
+                        <OpenAPISchemaProperties
+                            properties={properties}
+                            circularRefs={circularRefs}
+                            context={context}
+                        />
+                    ) : null}
+                    {schema.enum && schema.enum.length > 0 ? (
+                        <OpenAPISchemaEnum enumValues={schema.enum} />
+                    ) : null}
+                    {parentCircularRef ? (
+                        <OpenAPISchemaCircularRef id={parentCircularRef} schema={schema} />
+                    ) : null}
+                </>
+            ) : null}
+        </InteractiveSection>
+    );
+}
+
+/**
+ * Render a set of properties of an OpenAPI schema.
+ */
+export function OpenAPISchemaProperties(props: {
+    id?: string;
+    properties: OpenAPISchemaPropertyEntry[];
+    circularRefs?: CircularRefsIds;
+    context: OpenAPIClientContext;
+}) {
+    const { id, properties, circularRefs, context } = props;
+
+    if (!properties.length) {
+        return null;
+    }
+
+    return (
+        <div id={id} className={classNames('openapi-schema-properties')}>
+            {properties.map((property) => (
+                <OpenAPISchemaProperty
+                    key={property.propertyName}
+                    circularRefs={circularRefs}
+                    {...property}
+                    context={context}
+                />
+            ))}
+        </div>
+    );
+}
+
+/**
+ * Render a root schema (such as the request body or response body).
+ */
+export function OpenAPIRootSchema(props: {
+    schema: OpenAPIV3.SchemaObject;
+    context: OpenAPIClientContext;
+}) {
+    const { schema, context } = props;
+
+    // Avoid recursing infinitely, and instead render a link to the parent schema
+    const properties = getSchemaProperties(schema);
+
+    if (properties && properties.length > 0) {
+        return <OpenAPISchemaProperties properties={properties} context={context} />;
+    }
+
+    return (
+        <OpenAPISchemaProperty schema={schema} context={context} className="openapi-schema-root" />
+    );
+}
+
+/**
+ * Render a tab for an alternative schema.
+ * It renders directly the properties if relevant;
+ * for primitives, it renders the schema itself.
+ */
+function OpenAPISchemaAlternative(props: {
+    schema: OpenAPIV3.SchemaObject;
+    circularRefs?: CircularRefsIds;
+    context: OpenAPIClientContext;
+}) {
+    const { schema, circularRefs, context } = props;
+    const id = useId();
+    const subProperties = getSchemaProperties(schema);
+
+    return (
+        <OpenAPISchemaProperties
+            id={id}
+            properties={subProperties ?? [{ schema }]}
+            circularRefs={subProperties ? new Map(circularRefs).set(schema, id) : circularRefs}
+            context={context}
+        />
+    );
+}
+
+/**
+ * Render a circular reference to a schema.
+ */
+function OpenAPISchemaCircularRef(props: { id: string; schema: OpenAPIV3.SchemaObject }) {
+    const { id, schema } = props;
+
+    return (
+        <div className="openapi-schema-circular">
+            Circular reference to <a href={`#${id}`}>{getSchemaTitle(schema)}</a>{' '}
+            <span className="openapi-schema-circular-glyph">↩</span>
+        </div>
+    );
+}
+
+/**
+ * Render the enum value for a schema.
+ */
+export function OpenAPISchemaEnum(props: { enumValues: any[] }) {
+    const { enumValues } = props;
+
+    return (
+        <div className="openapi-schema-enum">
+            {enumValues.map((value, index) => (
+                <span key={index} className="openapi-schema-enum-value">{`${value}`}</span>
+            ))}
+        </div>
+    );
+}
+
+/**
+ * Get the sub-properties of a schema.
+ */
+function getSchemaProperties(schema: OpenAPIV3.SchemaObject): null | OpenAPISchemaPropertyEntry[] {
+    if (schema.allOf) {
+        return schema.allOf.reduce((acc, subSchema) => {
+            const properties = getSchemaProperties(noReference(subSchema)) ?? [
+                {
+                    schema: noReference(subSchema),
+                },
+            ];
+            return [...acc, ...properties];
+        }, [] as OpenAPISchemaPropertyEntry[]);
+    }
+
+    // check array AND schema.items as this is sometimes null despite what the type indicates
+    if (schema.type === 'array' && !!schema.items) {
+        const items = noReference(schema.items);
+        const itemProperties = getSchemaProperties(items);
+        if (itemProperties) {
+            return itemProperties;
+        }
+
+        return [
+            {
+                propertyName: 'items',
+                schema: items,
+            },
+        ];
+    }
+
+    if (schema.type === 'object' || schema.properties) {
+        const result: OpenAPISchemaPropertyEntry[] = [];
+
+        if (schema.properties) {
+            Object.entries(schema.properties).forEach(([propertyName, rawPropertySchema]) => {
+                const propertySchema = noReference(rawPropertySchema);
+                if (propertySchema.deprecated) {
+                    return;
+                }
+
+                result.push({
+                    propertyName,
+                    required: Array.isArray(schema.required)
+                        ? schema.required.includes(propertyName)
+                        : undefined,
+                    schema: propertySchema,
+                });
+            });
+        }
+
+        if (schema.additionalProperties) {
+            const additionalProperties = noReference(schema.additionalProperties);
+
+            result.push({
+                propertyName: 'Other properties',
+                schema: additionalProperties === true ? {} : additionalProperties,
+            });
+        }
+
+        return result;
+    }
+
+    return null;
+}
+
+/**
+ * Get the alternatives to display for a schema.
+ */
+export function getSchemaAlternatives(
+    schema: OpenAPIV3.SchemaObject,
+    ancestors: Set<OpenAPIV3.SchemaObject> = new Set(),
+): null | [OpenAPIV3.SchemaObject[], OpenAPIV3.DiscriminatorObject | undefined] {
+    const downAncestors = new Set(ancestors).add(schema);
+
+    if (schema.anyOf) {
+        return [
+            flattenAlternatives('anyOf', schema.anyOf.map(noReference), downAncestors),
+            noReference(schema.discriminator),
+        ];
+    }
+
+    if (schema.oneOf) {
+        return [
+            flattenAlternatives('oneOf', schema.oneOf.map(noReference), downAncestors),
+            noReference(schema.discriminator),
+        ];
+    }
+
+    if (schema.allOf) {
+        // allOf is managed in `getSchemaProperties`
+        return null;
+    }
+
+    return null;
+}
+
+function flattenAlternatives(
+    alternativeType: 'oneOf' | 'allOf' | 'anyOf',
+    alternatives: OpenAPIV3.SchemaObject[],
+    ancestors: Set<OpenAPIV3.SchemaObject>,
+): OpenAPIV3.SchemaObject[] {
+    return alternatives.reduce((acc, alternative) => {
+        if (!!alternative[alternativeType] && !ancestors.has(alternative)) {
+            return [...acc, ...(getSchemaAlternatives(alternative, ancestors)?.[0] || [])];
+        }
+
+        return [...acc, alternative];
+    }, [] as OpenAPIV3.SchemaObject[]);
+}
+
+function getSchemaTitle(
+    schema: OpenAPIV3.SchemaObject,
+
+    /** If the title is inferred in a oneOf with discriminator, we can use it to optimize the title */
+    discriminator?: OpenAPIV3.DiscriminatorObject,
+): string {
+    if (schema.title) {
+        // If the schema has a title, use it
+        return schema.title;
+    }
+
+    // Try using the discriminator
+    if (discriminator && schema.properties) {
+        const discriminatorProperty = noReference(schema.properties[discriminator.propertyName]);
+        if (discriminatorProperty) {
+            if (discriminatorProperty.enum) {
+                return discriminatorProperty.enum.map((value) => value.toString()).join(' | ');
+            }
+        }
+    }
+
+    // Otherwise try to infer a nice title
+    let type = 'any';
+
+    if (schema.enum) {
+        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 = `array of ${getSchemaTitle(noReference(schema.items))}`;
+    } else if (schema.type || schema.properties) {
+        type = schema.type ?? 'object';
+
+        if (schema.format) {
+            type += ` (${schema.format})`;
+        }
+    } else 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';
+    }
+
+    if (SYMBOL_REF_RESOLVED in schema) {
+        type = `${schema[SYMBOL_REF_RESOLVED]} (${type})`;
+    }
+
+    if (schema.nullable) {
+        type = `nullable ${type}`;
+    }
+
+    return type;
+}

package/src/OpenAPISecurities.tsx

@@ -0,0 +1,71 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { OpenAPIClientContext } from './types';
+import { InteractiveSection } from './InteractiveSection';
+import { Markdown } from './Markdown';
+import { OpenAPIOperationData } from './fetchOpenAPIOperation';
+
+/**
+ * Present securities authorization that can be used for this operation.
+ */
+export function OpenAPISecurities(props: {
+    securities: OpenAPIOperationData['securities'];
+    context: OpenAPIClientContext;
+}) {
+    const { securities, context } = props;
+
+    if (securities.length === 0) {
+        return null;
+    }
+
+    return (
+        <InteractiveSection
+            header="Authorization"
+            className="openapi-securities"
+            toggeable
+            defaultOpened={false}
+            toggleCloseIcon={context.icons.chevronDown}
+            toggleOpenIcon={context.icons.chevronRight}
+            tabs={securities.map(([key, security]) => {
+                return {
+                    key: key,
+                    label: key,
+                    body: (
+                        <>
+                            <p className="openapi-securities-label">{getLabelForType(security)}</p>
+                            {security.description ? (
+                                <Markdown
+                                    source={security.description}
+                                    className="openapi-securities-description"
+                                />
+                            ) : null}
+                        </>
+                    ),
+                };
+            })}
+        />
+    );
+}
+
+function getLabelForType(security: OpenAPIV3.SecuritySchemeObject) {
+    switch (security.type) {
+        case 'apiKey':
+            return 'API Key';
+        case 'http':
+            if (security.scheme === 'basic') {
+                return 'Basic Auth';
+            }
+
+            if (security.scheme == 'bearer') {
+                return `Bearer Token ${security.bearerFormat ? `(${security.bearerFormat})` : ''}`;
+            }
+
+            return 'HTTP';
+        case 'oauth2':
+            return 'OAuth2';
+        case 'openIdConnect':
+            return 'OpenID Connect';
+        default:
+            // @ts-ignore
+            return security.type;
+    }
+}

package/src/OpenAPIServerURL.tsx

@@ -0,0 +1,65 @@
+import { OpenAPIV3 } from 'openapi-types';
+import { OpenAPIServerURLVariable } from './OpenAPIServerURLVariable';
+
+/**
+ * Show the url of the server with variables replaced by their default values.
+ */
+export function OpenAPIServerURL(props: { servers: OpenAPIV3.ServerObject[] }) {
+    const { servers } = props;
+    const server = servers[0];
+
+    const parts = parseServerURL(server?.url ?? '');
+
+    return (
+        <span>
+            {parts.map((part, i) => {
+                if (part.kind === 'text') {
+                    return <span key={i}>{part.text}</span>;
+                } else {
+                    if (!server.variables?.[part.name]) {
+                        return <span key={i}>{`{${part.name}}`}</span>;
+                    }
+
+                    return (
+                        <OpenAPIServerURLVariable
+                            key={i}
+                            name={part.name}
+                            variable={server.variables[part.name]}
+                        />
+                    );
+                }
+            })}
+        </span>
+    );
+}
+
+/**
+ * Get the default URL for the server.
+ */
+export function getServersURL(servers: OpenAPIV3.ServerObject[]): string {
+    const server = servers[0];
+    const parts = parseServerURL(server?.url ?? '');
+
+    return parts
+        .map((part) => {
+            if (part.kind === 'text') {
+                return part.text;
+            } else {
+                return server.variables?.[part.name]?.default ?? `{${part.name}}`;
+            }
+        })
+        .join('');
+}
+
+function parseServerURL(url: string) {
+    const parts = url.split(/{([^}]+)}/g);
+    const result: Array<{ kind: 'variable'; name: string } | { kind: 'text'; text: string }> = [];
+    for (let i = 0; i < parts.length; i++) {
+        if (i % 2 === 0) {
+            result.push({ kind: 'text', text: parts[i] });
+        } else {
+            result.push({ kind: 'variable', name: parts[i] });
+        }
+    }
+    return result;
+}

package/src/OpenAPIServerURLVariable.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+import classNames from 'classnames';
+import { OpenAPIV3 } from 'openapi-types';
+import React from 'react';
+
+/**
+ * Interactive component to show the value of a server variable and let the user change it.
+ */
+export function OpenAPIServerURLVariable(props: {
+    name: string;
+    variable: OpenAPIV3.ServerVariableObject;
+}) {
+    const { variable } = props;
+    return <span className={classNames('openapi-url-var')}>{variable.default}</span>;
+}

package/src/OpenAPISpec.tsx

@@ -0,0 +1,118 @@
+'use client';
+
+import { OpenAPIV3 } from 'openapi-types';
+
+import { OpenAPIOperationData, fromJSON } from './fetchOpenAPIOperation';
+import { InteractiveSection } from './InteractiveSection';
+import { OpenAPIRequestBody } from './OpenAPIRequestBody';
+import { OpenAPIResponses } from './OpenAPIResponses';
+import { OpenAPISchemaProperties } from './OpenAPISchema';
+import { OpenAPISecurities } from './OpenAPISecurities';
+import { OpenAPIClientContext } from './types';
+import { noReference } from './utils';
+
+/**
+ * Client component to render the spec for the request and response.
+ *
+ * We use a client component as rendering recursive JSON schema in the server is expensive
+ * (the entire schema is rendered at once, while the client component only renders the visible part)
+ */
+export function OpenAPISpec(props: { rawData: any; context: OpenAPIClientContext }) {
+    const { rawData, context } = props;
+
+    const parsedData = fromJSON(rawData) as OpenAPIOperationData;
+    const { operation, securities } = parsedData;
+
+    const parameterGroups = groupParameters((operation.parameters || []).map(noReference));
+
+    return (
+        <>
+            {securities.length > 0 ? (
+                <OpenAPISecurities securities={securities} context={context} />
+            ) : null}
+
+            {parameterGroups.map((group) => (
+                <InteractiveSection
+                    key={group.key}
+                    className="openapi-parameters"
+                    toggeable
+                    toggleOpenIcon={context.icons.chevronRight}
+                    toggleCloseIcon={context.icons.chevronDown}
+                    header={group.label}
+                    defaultOpened={group.key === 'path' || context.defaultInteractiveOpened}
+                >
+                    <OpenAPISchemaProperties
+                        properties={group.parameters.map((parameter) => ({
+                            propertyName: parameter.name,
+                            schema: {
+                                // Description of the parameter is defined at the parameter level
+                                // we use display it if the schema doesn't override it
+                                description: parameter.description,
+                                example: parameter.example,
+                                ...(noReference(parameter.schema) ?? {}),
+                            },
+                            required: parameter.required,
+                        }))}
+                        context={context}
+                    />
+                </InteractiveSection>
+            ))}
+
+            {operation.requestBody ? (
+                <OpenAPIRequestBody
+                    requestBody={noReference(operation.requestBody)}
+                    context={context}
+                />
+            ) : null}
+            {operation.responses ? (
+                <OpenAPIResponses responses={noReference(operation.responses)} context={context} />
+            ) : null}
+        </>
+    );
+}
+
+function groupParameters(parameters: OpenAPIV3.ParameterObject[]): Array<{
+    key: string;
+    label: string;
+    parameters: OpenAPIV3.ParameterObject[];
+}> {
+    const sorted = ['path', 'query', 'header'];
+
+    const groups: Array<{
+        key: string;
+        label: string;
+        parameters: OpenAPIV3.ParameterObject[];
+    }> = [];
+
+    parameters.forEach((parameter) => {
+        const key = parameter.in;
+        const label = getParameterGroupName(parameter.in);
+        const group = groups.find((group) => group.key === key);
+        if (group) {
+            group.parameters.push(parameter);
+        } else {
+            groups.push({
+                key,
+                label,
+                parameters: [parameter],
+            });
+        }
+    });
+
+    groups.sort((a, b) => sorted.indexOf(a.key) - sorted.indexOf(b.key));
+
+    return groups;
+}
+
+function getParameterGroupName(paramIn: string): string {
+    switch (paramIn) {
+        case 'path':
+            return 'Path parameters';
+        case 'query':
+            return 'Query parameters';
+        case 'header':
+            return 'Header parameters';
+        default:
+            return paramIn;
+    }
+}