@gitbook/react-openapi 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @gitbook/react-openapi
+
+## 0.2.0
+
+### Minor Changes
+
+-   57adb3e: Second release to fix publishing with changeset
+
+## 0.1.0
+
+### Minor Changes
+
+-   5f8a8fe: Initial release

package/README.md

@@ -0,0 +1,12 @@
+# `@gitbook/react-openapi`
+
+React components to render OpenAPI operations.
+
+## Features
+
+-   Generate code samples for the request
+-   Support custom cde samples with `x-codeSamples` (Redocly syntax)
+
+## TODO
+
+-   Support for trying out the request

package/package.json

@@ -0,0 +1,20 @@
+{
+    "name": "@gitbook/react-openapi",
+    "exports": "./src/index.ts",
+    "version": "0.2.0",
+    "dependencies": {
+        "@scalar/api-client-react": "^0.3.7",
+        "@scalar/oas-utils": "0.1.6",
+        "classnames": "^2.5.1",
+        "flatted": "^3.2.9",
+        "openapi-types": "^12.1.3",
+        "yaml": "1.10.2",
+        "swagger2openapi": "^7.0.8"
+    },
+    "devDependencies": {
+        "@types/swagger2openapi": "^7.0.4"
+    },
+    "peerDependencies": {
+        "react": "*"
+    }
+}

package/src/InteractiveSection.tsx

@@ -0,0 +1,129 @@
+'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: {
+    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<{
+        key: string;
+        label: string;
+        body: React.ReactNode;
+    }>;
+    /** 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;
+}) {
+    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 [selectedTab, setSelectedTab] = React.useState(defaultTab);
+
+    const tabBody = tabs.find((tab) => tab.key === selectedTab)?.body;
+
+    return (
+        <div
+            id={id}
+            className={classNames(
+                'openapi-section',
+                toggeable ? 'openapi-section-toggeable' : null,
+                className,
+                toggeable ? `${className}-${opened ? 'opened' : 'closed'}` : null,
+            )}
+        >
+            <div
+                onClick={() => {
+                    if (toggeable) {
+                        setOpened(!opened);
+                    }
+                }}
+                className={classNames('openapi-section-header', `${className}-header`)}
+            >
+                <div
+                    className={classNames(
+                        'openapi-section-header-content',
+                        `${className}-header-content`,
+                    )}
+                >
+                    {header}
+                </div>
+                <div
+                    className={classNames(
+                        'openapi-section-header-controls',
+                        `${className}-header-controls`,
+                    )}
+                    onClick={(event) => {
+                        event.stopPropagation();
+                    }}
+                >
+                    {tabs.length ? (
+                        <select
+                            className={classNames(
+                                'openapi-section-select',
+                                'openapi-select',
+                                `${className}-tabs-select`,
+                            )}
+                            value={selectedTab}
+                            onChange={(event) => {
+                                setSelectedTab(event.target.value);
+                                setOpened(true);
+                            }}
+                        >
+                            {tabs.map((tab) => (
+                                <option key={tab.key} value={tab.key}>
+                                    {tab.label}
+                                </option>
+                            ))}
+                        </select>
+                    ) : null}
+                    {(children || tabBody) && toggeable ? (
+                        <button
+                            className={classNames('openapi-section-toggle', `${className}-toggle`)}
+                            onClick={() => setOpened(!opened)}
+                        >
+                            {opened ? toggleCloseIcon : toggleOpenIcon}
+                        </button>
+                    ) : null}
+                </div>
+            </div>
+            {(!toggeable || opened) && (children || tabBody) ? (
+                <div className={classNames('openapi-section-body', `${className}-body`)}>
+                    {children}
+                    {tabBody}
+                </div>
+            ) : null}
+            {overlay}
+        </div>
+    );
+}

package/src/Markdown.tsx

@@ -0,0 +1,12 @@
+import classNames from 'classnames';
+
+export function Markdown(props: { source: string; className?: string }) {
+    const { source, className } = props;
+
+    return (
+        <div
+            className={classNames('openapi-markdown', className)}
+            dangerouslySetInnerHTML={{ __html: source }}
+        />
+    );
+}

package/src/OpenAPICodeSample.tsx

@@ -0,0 +1,111 @@
+import { OpenAPIV3 } from 'openapi-types';
+
+import { CodeSampleInput, codeSampleGenerators } from './code-samples';
+import { OpenAPIOperationData, toJSON } from './fetchOpenAPIOperation';
+import { generateMediaTypeExample } from './generateSchemaExample';
+import { InteractiveSection } from './InteractiveSection';
+import { getServersURL } from './OpenAPIServerURL';
+import { ScalarApiButton } from './ScalarApiButton';
+import { OpenAPIContextProps } from './types';
+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: {
+    data: OpenAPIOperationData;
+    context: OpenAPIContextProps;
+}) {
+    const { data, context } = props;
+
+    const requestBody = noReference(data.operation.requestBody);
+    const requestBodyContent = requestBody ? Object.entries(requestBody.content)[0] : undefined;
+
+    const input: CodeSampleInput = {
+        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: <context.CodeBlock code={generator.generate(input)} syntax={generator.syntax} />,
+    }));
+
+    // Use custom samples if defined
+    let customCodeSamples: null | Array<{
+        key: string;
+        label: string;
+        body: React.ReactNode;
+    }> = null;
+    (['x-custom-examples', 'x-code-samples', 'x-codeSamples'] as const).forEach((key) => {
+        const customSamples = data.operation[key];
+        if (customSamples) {
+            customCodeSamples = customSamples.map((sample) => ({
+                key: `redocly-${sample.lang}`,
+                label: sample.label,
+                body: <context.CodeBlock code={sample.source} syntax={sample.lang} />,
+            }));
+        }
+    });
+
+    const samples = customCodeSamples ?? (data['x-codeSamples'] !== false ? autoCodeSamples : []);
+    if (samples.length === 0) {
+        return null;
+    }
+
+    async function fetchOperationData() {
+        'use server';
+        return toJSON(data);
+    }
+
+    return (
+        <InteractiveSection
+            header="Request"
+            className="openapi-codesample"
+            tabs={samples}
+            overlay={
+                data['x-hideTryItPanel'] || data.operation['x-hideTryItPanel'] ? null : (
+                    <ScalarApiButton fetchOperationData={fetchOperationData} />
+                )
+            }
+        />
+    );
+}
+
+function getSecurityHeaders(securities: OpenAPIOperationData['securities']): {
+    [key: string]: string;
+} {
+    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/src/OpenAPIOperation.tsx

@@ -0,0 +1,65 @@
+import classNames from 'classnames';
+
+import { OpenAPIOperationData, toJSON } from './fetchOpenAPIOperation';
+import { Markdown } from './Markdown';
+import { OpenAPICodeSample } from './OpenAPICodeSample';
+import { OpenAPIResponseExample } from './OpenAPIResponseExample';
+import { OpenAPIServerURL } from './OpenAPIServerURL';
+import { OpenAPISpec } from './OpenAPISpec';
+import { ScalarApiClient } from './ScalarApiButton';
+import { OpenAPIClientContext, OpenAPIContextProps } from './types';
+
+/**
+ * Display an interactive OpenAPI operation.
+ */
+export function OpenAPIOperation(props: {
+    className?: string;
+    data: OpenAPIOperationData;
+    context: OpenAPIContextProps;
+}) {
+    const { className, data, context } = props;
+    const { operation, servers, method, path } = data;
+
+    const clientContext: OpenAPIClientContext = {
+        defaultInteractiveOpened: context.defaultInteractiveOpened,
+        icons: context.icons,
+    };
+
+    return (
+        <ScalarApiClient>
+            <div className={classNames('openapi-operation', className)}>
+                <div className="openapi-intro">
+                    <h2 className="openapi-summary">{operation.summary}</h2>
+                    {operation.description ? (
+                        <Markdown className="openapi-description" source={operation.description} />
+                    ) : null}
+                    <div className="openapi-target">
+                        <span
+                            className={classNames(
+                                'openapi-method',
+                                `openapi-method-${method.toLowerCase()}`,
+                            )}
+                        >
+                            {method.toUpperCase()}
+                        </span>
+                        <span className="openapi-url">
+                            <OpenAPIServerURL servers={servers} />
+                            {path}
+                        </span>
+                    </div>
+                </div>
+                <div className={classNames('openapi-columns')}>
+                    <div className={classNames('openapi-column-spec')}>
+                        <OpenAPISpec rawData={toJSON(data)} context={clientContext} />
+                    </div>
+                    <div className={classNames('openapi-column-preview')}>
+                        <div className={classNames('openapi-column-preview-body')}>
+                            <OpenAPICodeSample {...props} />
+                            <OpenAPIResponseExample {...props} />
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </ScalarApiClient>
+    );
+}

package/src/OpenAPIRequestBody.tsx

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

package/src/OpenAPIResponse.tsx

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

package/src/OpenAPIResponseExample.tsx

@@ -0,0 +1,71 @@
+import { InteractiveSection } from './InteractiveSection';
+import { OpenAPIOperationData } from './fetchOpenAPIOperation';
+import { generateSchemaExample } from './generateSchemaExample';
+import { OpenAPIContextProps } from './types';
+import { noReference } from './utils';
+
+/**
+ * Display an example of the response content.
+ */
+export function OpenAPIResponseExample(props: {
+    data: OpenAPIOperationData;
+    context: OpenAPIContextProps;
+}) {
+    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 (
+        <InteractiveSection header="Response" className="openapi-response-example">
+            <context.CodeBlock
+                code={typeof example === 'string' ? example : JSON.stringify(example, null, 2)}
+                syntax="json"
+            />
+        </InteractiveSection>
+    );
+}

package/src/OpenAPIResponses.tsx

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

package/src/OpenAPISchema.test.ts

@@ -0,0 +1,101 @@
+import { it, describe, expect } from 'bun:test';
+import { getSchemaAlternatives } from './OpenAPISchema';
+import { OpenAPIV3 } from 'openapi-types';
+
+describe('getSchemaAlternatives', () => {
+    it('should flatten oneOf', () => {
+        expect(
+            getSchemaAlternatives({
+                oneOf: [
+                    {
+                        oneOf: [
+                            {
+                                type: 'number',
+                            },
+                            {
+                                type: 'boolean',
+                            },
+                        ],
+                    },
+                    {
+                        type: 'string',
+                    },
+                ],
+            }),
+        ).toEqual([
+            [
+                {
+                    type: 'number',
+                },
+                {
+                    type: 'boolean',
+                },
+                {
+                    type: 'string',
+                },
+            ],
+            undefined,
+        ]);
+    });
+
+    it('should not flatten oneOf and allOf', () => {
+        expect(
+            getSchemaAlternatives({
+                oneOf: [
+                    {
+                        allOf: [
+                            {
+                                type: 'number',
+                            },
+                            {
+                                type: 'boolean',
+                            },
+                        ],
+                    },
+                    {
+                        type: 'string',
+                    },
+                ],
+            }),
+        ).toEqual([
+            [
+                {
+                    allOf: [
+                        {
+                            type: 'number',
+                        },
+                        {
+                            type: 'boolean',
+                        },
+                    ],
+                },
+                {
+                    type: 'string',
+                },
+            ],
+            undefined,
+        ]);
+    });
+
+    it('should stop at circular references', () => {
+        const a: OpenAPIV3.SchemaObject = {
+            anyOf: [
+                {
+                    type: 'string',
+                },
+            ],
+        };
+
+        a.anyOf!.push(a);
+
+        expect(getSchemaAlternatives(a)).toEqual([
+            [
+                {
+                    type: 'string',
+                },
+                a,
+            ],
+            undefined,
+        ]);
+    });
+});