@gitbook/react-openapi 1.0.1 → 1.0.3

package/dist/types.d.ts

@@ -1,9 +1,25 @@
 import type { OpenAPICustomOperationProperties, OpenAPICustomSpecProperties, OpenAPIV3 } from '@gitbook/openapi-parser';
 export interface OpenAPIContextProps extends OpenAPIClientContext {
-    CodeBlock: React.ComponentType<{
+    /**
+     * Render a code block.
+     */
+    renderCodeBlock: (props: {
         code: string;
         syntax: string;
-    }>;
+    }) => React.ReactNode;
+    /**
+     * Render the heading of the operation.
+     */
+    renderHeading: (props: {
+        deprecated: boolean;
+        title: string;
+    }) => React.ReactNode;
+    /**
+     * Render the document of the operation.
+     */
+    renderDocument: (props: {
+        document: object;
+    }) => React.ReactNode;
     /** Spec url for the Scalar Api Client */
     specUrl: string;
 }

package/dist/util/server.d.ts

@@ -0,0 +1,9 @@
+import { OpenAPIV3 } from '@gitbook/openapi-parser';
+/**
+ * Get the default URL for the server.
+ */
+export declare function getDefaultServerURL(servers: OpenAPIV3.ServerObject[]): string;
+/**
+ * Interpolate the server URL with the default values of the variables.
+ */
+export declare function interpolateServerURL(server: OpenAPIV3.ServerObject): string;

package/dist/{OpenAPIServerURL.jsx → util/server.js}

@@ -1,40 +1,19 @@
-import { OpenAPIServerURLVariable } from './OpenAPIServerURLVariable';
 /**
- * Show the url of the server with variables replaced by their default values.
+ * Get the default URL for the server.
  */
-export function OpenAPIServerURL(props) {
-    var _a;
-    var servers = props.servers;
+export function getDefaultServerURL(servers) {
     var server = servers[0];
     if (!server) {
-        return null;
+        // Return empty string if no server is found to display nothing
+        return '';
     }
-    var parts = parseServerURL((_a = server === null || server === void 0 ? void 0 : server.url) !== null && _a !== void 0 ? _a : '');
-    return (<span>
-            {parts.map(function (part, i) {
-            var _a;
-            if (part.kind === 'text') {
-                return <span key={i}>{part.text}</span>;
-            }
-            else {
-                var variable = (_a = server.variables) === null || _a === void 0 ? void 0 : _a[part.name];
-                if (!variable) {
-                    return <span key={i}>{"{".concat(part.name, "}")}</span>;
-                }
-                return (<OpenAPIServerURLVariable key={i} name={part.name} variable={variable}/>);
-            }
-        })}
-        </span>);
+    return interpolateServerURL(server);
 }
 /**
- * Get the default URL for the server.
+ * Interpolate the server URL with the default values of the variables.
  */
-export function getServersURL(servers) {
+export function interpolateServerURL(server) {
     var _a;
-    var server = servers[0];
-    if (!server) {
-        return '';
-    }
     var parts = parseServerURL((_a = server === null || server === void 0 ? void 0 : server.url) !== null && _a !== void 0 ? _a : '');
     return parts
         .map(function (part) {

package/dist/utils.d.ts

@@ -1,7 +1,31 @@
-import type { AnyObject, OpenAPIV3 } from '@gitbook/openapi-parser';
-export declare function checkIsReference(input: unknown): input is OpenAPIV3.ReferenceObject;
+import type { AnyObject, OpenAPIV3, OpenAPIV3_1 } from '@gitbook/openapi-parser';
+export declare function checkIsReference(input: unknown): input is OpenAPIV3.ReferenceObject | OpenAPIV3_1.ReferenceObject;
 export declare function createStateKey(key: string, scope?: string): string;
 /**
  * Resolve the description of an object.
  */
-export declare function resolveDescription(object: AnyObject): string | undefined;
+export declare function resolveDescription(object: OpenAPIV3.SchemaObject | AnyObject): string | undefined;
+/**
+ * Extract descriptions from an object.
+ */
+export declare function extractDescriptions(object: AnyObject): {
+    description: any;
+    "x-gitbook-description-html": any;
+};
+/**
+ * Resolve the first example from an object.
+ */
+export declare function resolveFirstExample(object: AnyObject): any;
+/**
+ * Resolve the schema of a parameter.
+ * Extract the description, example and deprecated from parameter.
+ */
+export declare function resolveParameterSchema(parameter: OpenAPIV3.ParameterBaseObject): OpenAPIV3.SchemaObject;
+/**
+ * Transform a parameter object to a property object.
+ */
+export declare function parameterToProperty(parameter: OpenAPIV3.ParameterObject | OpenAPIV3.ReferenceObject | OpenAPIV3_1.ReferenceObject): {
+    propertyName: string | undefined;
+    schema: OpenAPIV3.SchemaObject;
+    required: boolean | undefined;
+};

package/dist/utils.js

@@ -1,3 +1,14 @@
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
 export function checkIsReference(input) {
     return typeof input === 'object' && !!input && '$ref' in input;
 }
@@ -8,9 +19,70 @@ export function createStateKey(key, scope) {
  * Resolve the description of an object.
  */
 export function resolveDescription(object) {
-    return 'x-description-html' in object && typeof object['x-description-html'] === 'string'
-        ? object['x-description-html']
+    if ('items' in object && object.items) {
+        return resolveDescription(object.items);
+    }
+    return 'x-gitbook-description-html' in object &&
+        typeof object['x-gitbook-description-html'] === 'string'
+        ? object['x-gitbook-description-html'].trim()
         : typeof object.description === 'string'
-            ? object.description
+            ? object.description.trim()
             : undefined;
 }
+/**
+ * Extract descriptions from an object.
+ */
+export function extractDescriptions(object) {
+    var _a;
+    return _a = {
+            description: object.description
+        },
+        _a['x-gitbook-description-html'] = 'x-gitbook-description-html' in object
+            ? object['x-gitbook-description-html']
+            : undefined,
+        _a;
+}
+/**
+ * Resolve the first example from an object.
+ */
+export function resolveFirstExample(object) {
+    if ('examples' in object && typeof object.examples === 'object' && object.examples) {
+        var keys = Object.keys(object.examples);
+        var firstKey = keys[0];
+        if (firstKey && object.examples[firstKey]) {
+            return object.examples[firstKey];
+        }
+    }
+    if ('example' in object && object.example !== undefined) {
+        return object.example;
+    }
+    return undefined;
+}
+/**
+ * Resolve the schema of a parameter.
+ * Extract the description, example and deprecated from parameter.
+ */
+export function resolveParameterSchema(parameter) {
+    var schema = checkIsReference(parameter.schema) ? undefined : parameter.schema;
+    return __assign(__assign(__assign({}, extractDescriptions(parameter)), { example: resolveFirstExample(parameter), 
+        // Deprecated can be defined at the parameter level
+        deprecated: parameter.deprecated }), schema);
+}
+/**
+ * Transform a parameter object to a property object.
+ */
+export function parameterToProperty(parameter) {
+    var _a;
+    if (checkIsReference(parameter)) {
+        return {
+            propertyName: (_a = parameter.$ref) !== null && _a !== void 0 ? _a : 'Unknown ref',
+            schema: {},
+            required: undefined,
+        };
+    }
+    return {
+        propertyName: parameter.name,
+        schema: resolveParameterSchema(parameter),
+        required: parameter.required,
+    };
+}

package/package.json

@@ -8,7 +8,7 @@
             "default": "./dist/index.js"
         }
     },
-    "version": "1.0.1",
+    "version": "1.0.3",
     "sideEffects": false,
     "dependencies": {
         "@gitbook/openapi-parser": "workspace:*",
@@ -16,6 +16,7 @@
         "@scalar/oas-utils": "^0.2.101",
         "clsx": "^2.1.1",
         "flatted": "^3.2.9",
+        "json-xml-parse": "^1.3.0",
         "react-aria-components": "^1.6.0",
         "react-aria": "^3.37.0",
         "usehooks-ts": "^3.1.0",
@@ -29,7 +30,7 @@
         "react": "*"
     },
     "scripts": {
-        "build": "tsc --project tsconfig.build.json",
+        "build": "rm -rf ./dist && tsc --project tsconfig.build.json",
         "typecheck": "tsc --noEmit",
         "unit": "bun test",
         "dev": "bun run build -- --watch",

package/src/OpenAPICodeSample.tsx

@@ -1,12 +1,12 @@
 import { CodeSampleInput, codeSampleGenerators } from './code-samples';
 import { generateMediaTypeExample, generateSchemaExample } from './generateSchemaExample';
 import { InteractiveSection } from './InteractiveSection';
-import { getServersURL } from './OpenAPIServerURL';
 import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
 import { createStateKey } from './utils';
 import { stringifyOpenAPI } from './stringifyOpenAPI';
 import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
 import { checkIsReference } from './utils';
+import { getDefaultServerURL } from './util/server';
 
 /**
  * Display code samples to execute the operation.
@@ -53,13 +53,11 @@ export function OpenAPICodeSample(props: {
 
     const input: CodeSampleInput = {
         url:
-            getServersURL(data.servers) +
+            getDefaultServerURL(data.servers) +
             data.path +
             (searchParams.size ? `?${searchParams.toString()}` : ''),
         method: data.method,
-        body: requestBodyContent
-            ? generateMediaTypeExample(requestBodyContent[1], { onlyRequired: true })
-            : undefined,
+        body: requestBodyContent ? generateMediaTypeExample(requestBodyContent[1]) : undefined,
         headers: {
             ...getSecurityHeaders(data.securities),
             ...headersObject,
@@ -74,7 +72,10 @@ export function OpenAPICodeSample(props: {
     const autoCodeSamples = codeSampleGenerators.map((generator) => ({
         key: `default-${generator.id}`,
         label: generator.label,
-        body: <context.CodeBlock code={generator.generate(input)} syntax={generator.syntax} />,
+        body: context.renderCodeBlock({
+            code: generator.generate(input),
+            syntax: generator.syntax,
+        }),
     }));
 
     // Use custom samples if defined
@@ -97,7 +98,10 @@ export function OpenAPICodeSample(props: {
                 .map((sample) => ({
                     key: `redocly-${sample.lang}`,
                     label: sample.label,
-                    body: <context.CodeBlock code={sample.source} syntax={sample.lang} />,
+                    body: context.renderCodeBlock({
+                        code: sample.source,
+                        syntax: sample.lang,
+                    }),
                 }));
         }
     });

package/src/OpenAPIOperation.tsx

@@ -7,6 +7,7 @@ import { OpenAPISpec } from './OpenAPISpec';
 import type { OpenAPIClientContext, OpenAPIContextProps, OpenAPIOperationData } from './types';
 import { OpenAPIPath } from './OpenAPIPath';
 import { resolveDescription } from './utils';
+import { OpenAPICustomOperationProperties, OpenAPIV3 } from '@gitbook/openapi-parser';
 
 /**
  * Display an interactive OpenAPI operation.
@@ -25,14 +26,15 @@ export function OpenAPIOperation(props: {
         blockKey: context.blockKey,
     };
 
-    const description = resolveDescription(operation)?.trim();
-
     return (
         <div className={clsx('openapi-operation', className)}>
-            <div className="openapi-summary" id={context.id}>
-                <h2 className="openapi-summary-title" data-deprecated={operation.deprecated}>
-                    {operation.summary}
-                </h2>
+            <div className="openapi-summary" id={operation.summary ? undefined : context.id}>
+                {operation.summary
+                    ? context.renderHeading({
+                          deprecated: operation.deprecated ?? false,
+                          title: operation.summary,
+                      })
+                    : null}
                 {operation.deprecated && <div className="openapi-deprecated">Deprecated</div>}
             </div>
             <div className="openapi-columns">
@@ -46,11 +48,7 @@ export function OpenAPIOperation(props: {
                             {`.`}
                         </div>
                     ) : null}
-                    {description ? (
-                        <div className="openapi-intro">
-                            <Markdown className="openapi-description" source={description} />
-                        </div>
-                    ) : null}
+                    <OpenAPIOperationDescription operation={operation} context={context} />
                     <OpenAPIPath data={data} context={context} />
                     <OpenAPISpec data={data} context={clientContext} />
                 </div>
@@ -64,3 +62,30 @@ export function OpenAPIOperation(props: {
         </div>
     );
 }
+
+function OpenAPIOperationDescription(props: {
+    operation: OpenAPIV3.OperationObject<OpenAPICustomOperationProperties>;
+    context: OpenAPIContextProps;
+}) {
+    const { operation } = props;
+    if (operation['x-gitbook-description-document']) {
+        return (
+            <div className="openapi-intro">
+                {props.context.renderDocument({
+                    document: operation['x-gitbook-description-document'],
+                })}
+            </div>
+        );
+    }
+
+    const description = resolveDescription(operation);
+    if (!description) {
+        return null;
+    }
+
+    return (
+        <div className="openapi-intro">
+            <Markdown className="openapi-description" source={description} />
+        </div>
+    );
+}

package/src/OpenAPIResponse.tsx

@@ -1,6 +1,6 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import { OpenAPISchemaProperties } from './OpenAPISchema';
-import { resolveDescription } from './utils';
+import { parameterToProperty, resolveDescription } from './utils';
 import type { OpenAPIClientContext } from './types';
 import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 
@@ -27,13 +27,11 @@ export function OpenAPIResponse(props: {
     return (
         <div className="openapi-response-body">
             {headers.length > 0 ? (
-                <OpenAPIDisclosure context={context} label={'Headers'}>
+                <OpenAPIDisclosure context={context} label="Headers">
                     <OpenAPISchemaProperties
-                        properties={headers.map(([name, header]) => ({
-                            propertyName: name,
-                            schema: header.schema ?? {},
-                            required: header.required,
-                        }))}
+                        properties={headers.map(([name, header]) => {
+                            return parameterToProperty({ name, ...header });
+                        })}
                         context={context}
                     />
                 </OpenAPIDisclosure>
@@ -41,11 +39,7 @@ export function OpenAPIResponse(props: {
             <div className="openapi-responsebody">
                 <OpenAPISchemaProperties
                     id={`response-${context.blockKey}`}
-                    properties={[
-                        {
-                            schema: mediaType.schema ?? {},
-                        },
-                    ]}
+                    properties={mediaType.schema ? [{ schema: mediaType.schema }] : []}
                     context={context}
                 />
             </div>