@gitbook/react-openapi 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @gitbook/react-openapi
 
+## 0.6.0
+
+### Minor Changes
+
+-   709f1a1: Update Scalar to the latest version, with faster performances and an improved experience
+
+### Patch Changes
+
+-   ede2335: Fix x-codeSamples: false not working at the single operation level
+-   0426312: Fix tabs being empty for code samples when they are updated dynamically
+
+## 0.5.0
+
+### Minor Changes
+
+-   3445db4: Fix files published in the NPM packages by defining "files" in "package.json"
+
 ## 0.4.0
 
 ### Minor Changes

package/dist/InteractiveSection.d.ts

@@ -0,0 +1,33 @@
+import React from 'react';
+interface InteractiveSectionTab {
+    key: string;
+    label: string;
+    body: React.ReactNode;
+}
+/**
+ * To optimize rendering, most of the components are server-components,
+ * and the interactiveness is mainly handled by a few key components like this one.
+ */
+export declare function InteractiveSection(props: {
+    id?: string;
+    /** Class name to be set on the section, sub-elements will use it as prefix */
+    className: string;
+    /** If true, the content can be toggeable */
+    toggeable?: boolean;
+    /** Default state of the toggle */
+    defaultOpened?: boolean;
+    /** Icons to display for the toggle */
+    toggleOpenIcon?: React.ReactNode;
+    toggleCloseIcon?: React.ReactNode;
+    /** Tabs of content to display */
+    tabs?: Array<InteractiveSectionTab>;
+    /** Default tab to have opened */
+    defaultTab?: string;
+    /** Content of the header */
+    header: React.ReactNode;
+    /** Body of the section */
+    children?: React.ReactNode;
+    /** Children to display within the container */
+    overlay?: React.ReactNode;
+}): React.JSX.Element;
+export {};

package/dist/InteractiveSection.js

@@ -0,0 +1,32 @@
+'use client';
+import classNames from 'classnames';
+import React from 'react';
+/**
+ * To optimize rendering, most of the components are server-components,
+ * and the interactiveness is mainly handled by a few key components like this one.
+ */
+export function InteractiveSection(props) {
+    const { id, className, toggeable = false, defaultOpened = true, tabs = [], defaultTab = tabs[0]?.key, header, children, overlay, toggleOpenIcon = '▶', toggleCloseIcon = '▼', } = props;
+    const [opened, setOpened] = React.useState(defaultOpened);
+    const [selectedTabKey, setSelectedTab] = React.useState(defaultTab);
+    const selectedTab = tabs.find((tab) => tab.key === selectedTabKey) ?? tabs[0];
+    return (React.createElement("div", { id: id, className: classNames('openapi-section', toggeable ? 'openapi-section-toggeable' : null, className, toggeable ? `${className}-${opened ? 'opened' : 'closed'}` : null) },
+        React.createElement("div", { onClick: () => {
+                if (toggeable) {
+                    setOpened(!opened);
+                }
+            }, className: classNames('openapi-section-header', `${className}-header`) },
+            React.createElement("div", { className: classNames('openapi-section-header-content', `${className}-header-content`) }, header),
+            React.createElement("div", { className: classNames('openapi-section-header-controls', `${className}-header-controls`), onClick: (event) => {
+                    event.stopPropagation();
+                } },
+                tabs.length ? (React.createElement("select", { className: classNames('openapi-section-select', 'openapi-select', `${className}-tabs-select`), value: selectedTab.key, onChange: (event) => {
+                        setSelectedTab(event.target.value);
+                        setOpened(true);
+                    } }, tabs.map((tab) => (React.createElement("option", { key: tab.key, value: tab.key }, tab.label))))) : null,
+                (children || selectedTab?.body) && toggeable ? (React.createElement("button", { className: classNames('openapi-section-toggle', `${className}-toggle`), onClick: () => setOpened(!opened) }, opened ? toggleCloseIcon : toggleOpenIcon)) : null)),
+        (!toggeable || opened) && (children || selectedTab?.body) ? (React.createElement("div", { className: classNames('openapi-section-body', `${className}-body`) },
+            children,
+            selectedTab?.body)) : null,
+        overlay));
+}

package/dist/Markdown.d.ts

@@ -0,0 +1,5 @@
+import * as React from 'react';
+export declare function Markdown(props: {
+    source: string;
+    className?: string;
+}): React.JSX.Element;

package/dist/Markdown.js

@@ -0,0 +1,6 @@
+import * as React from 'react';
+import classNames from 'classnames';
+export function Markdown(props) {
+    const { source, className } = props;
+    return (React.createElement("div", { className: classNames('openapi-markdown', className), dangerouslySetInnerHTML: { __html: source } }));
+}

package/dist/OpenAPICodeSample.d.ts

@@ -0,0 +1,11 @@
+import * as React from 'react';
+import { OpenAPIOperationData } from './fetchOpenAPIOperation';
+import { OpenAPIContextProps } from './types';
+/**
+ * Display code samples to execute the operation.
+ * It supports the Redocly custom syntax as well (https://redocly.com/docs/api-reference-docs/specification-extensions/x-code-samples/)
+ */
+export declare function OpenAPICodeSample(props: {
+    data: OpenAPIOperationData;
+    context: OpenAPIContextProps;
+}): React.JSX.Element | null;

package/dist/OpenAPICodeSample.js

@@ -0,0 +1,76 @@
+import * as React from 'react';
+import { codeSampleGenerators } from './code-samples';
+import { generateMediaTypeExample } from './generateSchemaExample';
+import { InteractiveSection } from './InteractiveSection';
+import { getServersURL } from './OpenAPIServerURL';
+import { ScalarApiButton } from './ScalarApiButton';
+import { noReference } from './utils';
+/**
+ * Display code samples to execute the operation.
+ * It supports the Redocly custom syntax as well (https://redocly.com/docs/api-reference-docs/specification-extensions/x-code-samples/)
+ */
+export function OpenAPICodeSample(props) {
+    const { data, context } = props;
+    const requestBody = noReference(data.operation.requestBody);
+    const requestBodyContent = requestBody ? Object.entries(requestBody.content)[0] : undefined;
+    const input = {
+        url: getServersURL(data.servers) + data.path,
+        method: data.method,
+        body: requestBodyContent
+            ? generateMediaTypeExample(requestBodyContent[1], { onlyRequired: true })
+            : undefined,
+        headers: {
+            ...getSecurityHeaders(data.securities),
+            ...(requestBodyContent
+                ? {
+                    'Content-Type': requestBodyContent[0],
+                }
+                : undefined),
+        },
+    };
+    const autoCodeSamples = codeSampleGenerators.map((generator) => ({
+        key: `default-${generator.id}`,
+        label: generator.label,
+        body: React.createElement(context.CodeBlock, { code: generator.generate(input), syntax: generator.syntax }),
+    }));
+    // Use custom samples if defined
+    let customCodeSamples = null;
+    ['x-custom-examples', 'x-code-samples', 'x-codeSamples'].forEach((key) => {
+        const customSamples = data.operation[key];
+        if (customSamples && Array.isArray(customSamples)) {
+            customCodeSamples = customSamples.map((sample) => ({
+                key: `redocly-${sample.lang}`,
+                label: sample.label,
+                body: React.createElement(context.CodeBlock, { code: sample.source, syntax: sample.lang }),
+            }));
+        }
+    });
+    // Code samples can be disabled at the top-level or at the operation level
+    // If code samples are defined at the operation level, it will override the top-level setting
+    const codeSamplesDisabled = data['x-codeSamples'] === false || data.operation['x-codeSamples'] === false;
+    const samples = customCodeSamples ?? (!codeSamplesDisabled ? autoCodeSamples : []);
+    if (samples.length === 0) {
+        return null;
+    }
+    return (React.createElement(InteractiveSection, { header: "Request", className: "openapi-codesample", tabs: samples, overlay: data['x-hideTryItPanel'] || data.operation['x-hideTryItPanel'] ? null : (React.createElement(ScalarApiButton, null)) }));
+}
+function getSecurityHeaders(securities) {
+    const security = securities[0];
+    if (!security) {
+        return {};
+    }
+    switch (security[1].type) {
+        case 'http': {
+            let scheme = security[1].scheme;
+            if (scheme === 'bearer') {
+                scheme = 'Bearer';
+            }
+            return {
+                Authorization: scheme + ' ' + (security[1].bearerFormat ?? '<token>'),
+            };
+        }
+        default: {
+            return {};
+        }
+    }
+}

package/dist/OpenAPIOperation.d.ts

@@ -0,0 +1,11 @@
+import * as React from 'react';
+import { OpenAPIOperationData } from './fetchOpenAPIOperation';
+import { OpenAPIContextProps } from './types';
+/**
+ * Display an interactive OpenAPI operation.
+ */
+export declare function OpenAPIOperation(props: {
+    className?: string;
+    data: OpenAPIOperationData;
+    context: OpenAPIContextProps;
+}): React.JSX.Element;

package/dist/OpenAPIOperation.js

@@ -0,0 +1,38 @@
+import * as React from 'react';
+import classNames from 'classnames';
+import { toJSON } from './fetchOpenAPIOperation';
+import { Markdown } from './Markdown';
+import { OpenAPICodeSample } from './OpenAPICodeSample';
+import { OpenAPIResponseExample } from './OpenAPIResponseExample';
+import { OpenAPIServerURL } from './OpenAPIServerURL';
+import { OpenAPISpec } from './OpenAPISpec';
+import { ApiClientModalProvider } from '@scalar/api-client-react';
+/**
+ * Display an interactive OpenAPI operation.
+ */
+export function OpenAPIOperation(props) {
+    const { className, data, context } = props;
+    const { operation, servers, method, path } = data;
+    const clientContext = {
+        defaultInteractiveOpened: context.defaultInteractiveOpened,
+        specUrl: context.specUrl,
+        icons: context.icons,
+    };
+    return (React.createElement(ApiClientModalProvider, { configuration: { spec: { url: context.specUrl } }, initialRequest: { path: data.path, method: data.method } },
+        React.createElement("div", { className: classNames('openapi-operation', className) },
+            React.createElement("div", { className: "openapi-intro" },
+                React.createElement("h2", { className: "openapi-summary" }, operation.summary),
+                operation.description ? (React.createElement(Markdown, { className: "openapi-description", source: operation.description })) : null,
+                React.createElement("div", { className: "openapi-target" },
+                    React.createElement("span", { className: classNames('openapi-method', `openapi-method-${method.toLowerCase()}`) }, method.toUpperCase()),
+                    React.createElement("span", { className: "openapi-url" },
+                        React.createElement(OpenAPIServerURL, { servers: servers }),
+                        path))),
+            React.createElement("div", { className: classNames('openapi-columns') },
+                React.createElement("div", { className: classNames('openapi-column-spec') },
+                    React.createElement(OpenAPISpec, { rawData: toJSON(data), context: clientContext })),
+                React.createElement("div", { className: classNames('openapi-column-preview') },
+                    React.createElement("div", { className: classNames('openapi-column-preview-body') },
+                        React.createElement(OpenAPICodeSample, { ...props }),
+                        React.createElement(OpenAPIResponseExample, { ...props })))))));
+}

package/dist/OpenAPIRequestBody.d.ts

@@ -0,0 +1,10 @@
+import * as React from 'react';
+import { OpenAPIV3 } from 'openapi-types';
+import { OpenAPIClientContext } from './types';
+/**
+ * Display an interactive request body.
+ */
+export declare function OpenAPIRequestBody(props: {
+    requestBody: OpenAPIV3.RequestBodyObject;
+    context: OpenAPIClientContext;
+}): React.JSX.Element;

package/dist/OpenAPIRequestBody.js

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import { OpenAPIRootSchema } from './OpenAPISchema';
+import { noReference } from './utils';
+import { InteractiveSection } from './InteractiveSection';
+import { Markdown } from './Markdown';
+/**
+ * Display an interactive request body.
+ */
+export function OpenAPIRequestBody(props) {
+    const { requestBody, context } = props;
+    return (React.createElement(InteractiveSection, { header: "Body", className: "openapi-requestbody", tabs: Object.entries(requestBody.content ?? {}).map(([contentType, mediaTypeObject]) => {
+            return {
+                key: contentType,
+                label: contentType,
+                body: (React.createElement(OpenAPIRootSchema, { schema: noReference(mediaTypeObject.schema) ?? {}, context: context })),
+            };
+        }), defaultOpened: context.defaultInteractiveOpened }, requestBody.description ? (React.createElement(Markdown, { source: requestBody.description, className: "openapi-requestbody-description" })) : null));
+}

package/dist/OpenAPIResponse.d.ts

@@ -0,0 +1,10 @@
+import * as React from 'react';
+import { OpenAPIV3 } from 'openapi-types';
+import { OpenAPIClientContext } from './types';
+/**
+ * Display an interactive response body.
+ */
+export declare function OpenAPIResponse(props: {
+    response: OpenAPIV3.ResponseObject;
+    context: OpenAPIClientContext;
+}): React.JSX.Element | null;

package/dist/OpenAPIResponse.js

@@ -0,0 +1,32 @@
+import * as React from 'react';
+import classNames from 'classnames';
+import { OpenAPIRootSchema, OpenAPISchemaProperties } from './OpenAPISchema';
+import { noReference } from './utils';
+import { InteractiveSection } from './InteractiveSection';
+import { Markdown } from './Markdown';
+/**
+ * Display an interactive response body.
+ */
+export function OpenAPIResponse(props) {
+    const { response, context } = props;
+    const content = Object.entries(response.content ?? {});
+    const headers = Object.entries(response.headers ?? {}).map(([name, header]) => [name, noReference(header) ?? {}]);
+    if (content.length === 0 && !response.description && headers.length === 0) {
+        return null;
+    }
+    return (React.createElement(React.Fragment, null,
+        response.description ? (React.createElement(Markdown, { source: response.description, className: "openapi-response-description" })) : null,
+        headers.length > 0 ? (React.createElement(InteractiveSection, { toggeable: true, defaultOpened: !!context.defaultInteractiveOpened, toggleCloseIcon: context.icons.chevronDown, toggleOpenIcon: context.icons.chevronRight, header: "Headers", className: classNames('openapi-responseheaders') },
+            React.createElement(OpenAPISchemaProperties, { properties: headers.map(([name, header]) => ({
+                    propertyName: name,
+                    schema: noReference(header.schema) ?? {},
+                    required: header.required,
+                })), context: context }))) : null,
+        content.length > 0 ? (React.createElement(InteractiveSection, { header: "Body", className: classNames('openapi-responsebody'), tabs: content.map(([contentType, mediaType]) => {
+                return {
+                    key: contentType,
+                    label: contentType,
+                    body: (React.createElement(OpenAPIRootSchema, { schema: noReference(mediaType.schema) ?? {}, context: context })),
+                };
+            }) })) : null));
+}

package/dist/OpenAPIResponseExample.d.ts

@@ -0,0 +1,10 @@
+import * as React from 'react';
+import { OpenAPIOperationData } from './fetchOpenAPIOperation';
+import { OpenAPIContextProps } from './types';
+/**
+ * Display an example of the response content.
+ */
+export declare function OpenAPIResponseExample(props: {
+    data: OpenAPIOperationData;
+    context: OpenAPIContextProps;
+}): React.JSX.Element | null;

package/dist/OpenAPIResponseExample.js

@@ -0,0 +1,48 @@
+import * as React from 'react';
+import { InteractiveSection } from './InteractiveSection';
+import { generateSchemaExample } from './generateSchemaExample';
+import { noReference } from './utils';
+/**
+ * Display an example of the response content.
+ */
+export function OpenAPIResponseExample(props) {
+    const { data, context } = props;
+    // if there are no responses defined for the operation
+    if (!data.operation.responses) {
+        return null;
+    }
+    const responses = Object.entries(data.operation.responses);
+    // Sort response to get 200, and 2xx first
+    responses.sort(([a], [b]) => {
+        if (a === 'default') {
+            return 1;
+        }
+        if (b === 'default') {
+            return -1;
+        }
+        if (a === '200') {
+            return -1;
+        }
+        if (b === '200') {
+            return 1;
+        }
+        return Number(a) - Number(b);
+    });
+    // Take the first one
+    const response = responses[0];
+    if (!response) {
+        return null;
+    }
+    const responseObject = noReference(response[1]);
+    const schema = noReference((responseObject.content?.['application/json'] ??
+        responseObject.content?.[Object.keys(responseObject.content)[0]])?.schema);
+    if (!schema) {
+        return null;
+    }
+    const example = generateSchemaExample(schema);
+    if (example === undefined) {
+        return null;
+    }
+    return (React.createElement(InteractiveSection, { header: "Response", className: "openapi-response-example" },
+        React.createElement(context.CodeBlock, { code: typeof example === 'string' ? example : JSON.stringify(example, null, 2), syntax: "json" })));
+}

package/dist/OpenAPIResponses.d.ts

@@ -0,0 +1,10 @@
+import * as React from 'react';
+import { OpenAPIV3 } from 'openapi-types';
+import { OpenAPIClientContext } from './types';
+/**
+ * Display an interactive response body.
+ */
+export declare function OpenAPIResponses(props: {
+    responses: OpenAPIV3.ResponsesObject;
+    context: OpenAPIClientContext;
+}): React.JSX.Element;

package/dist/OpenAPIResponses.js

@@ -0,0 +1,18 @@
+import * as React from 'react';
+import classNames from 'classnames';
+import { noReference } from './utils';
+import { OpenAPIResponse } from './OpenAPIResponse';
+import { InteractiveSection } from './InteractiveSection';
+/**
+ * Display an interactive response body.
+ */
+export function OpenAPIResponses(props) {
+    const { responses, context } = props;
+    return (React.createElement(InteractiveSection, { header: "Response", className: classNames('openapi-responses'), tabs: Object.entries(responses).map(([statusCode, response]) => {
+            return {
+                key: statusCode,
+                label: statusCode,
+                body: React.createElement(OpenAPIResponse, { response: noReference(response), context: context }),
+            };
+        }) }));
+}

package/dist/OpenAPISchema.d.ts

@@ -0,0 +1,45 @@
+import { OpenAPIV3 } from 'openapi-types';
+import React from 'react';
+import { OpenAPIClientContext } from './types';
+type CircularRefsIds = Map<OpenAPIV3.SchemaObject, string>;
+interface OpenAPISchemaPropertyEntry {
+    propertyName?: string;
+    required?: boolean;
+    schema: OpenAPIV3.SchemaObject;
+}
+/**
+ * Render a property of an OpenAPI schema.
+ */
+export declare function OpenAPISchemaProperty(props: OpenAPISchemaPropertyEntry & {
+    /** Set of objects already observed as parents */
+    circularRefs?: CircularRefsIds;
+    context: OpenAPIClientContext;
+    className?: string;
+}): React.JSX.Element;
+/**
+ * Render a set of properties of an OpenAPI schema.
+ */
+export declare function OpenAPISchemaProperties(props: {
+    id?: string;
+    properties: OpenAPISchemaPropertyEntry[];
+    circularRefs?: CircularRefsIds;
+    context: OpenAPIClientContext;
+}): React.JSX.Element | null;
+/**
+ * Render a root schema (such as the request body or response body).
+ */
+export declare function OpenAPIRootSchema(props: {
+    schema: OpenAPIV3.SchemaObject;
+    context: OpenAPIClientContext;
+}): React.JSX.Element;
+/**
+ * Render the enum value for a schema.
+ */
+export declare function OpenAPISchemaEnum(props: {
+    enumValues: any[];
+}): React.JSX.Element;
+/**
+ * Get the alternatives to display for a schema.
+ */
+export declare function getSchemaAlternatives(schema: OpenAPIV3.SchemaObject, ancestors?: Set<OpenAPIV3.SchemaObject>): null | [OpenAPIV3.SchemaObject[], OpenAPIV3.DiscriminatorObject | undefined];
+export {};