@gitbook/react-openapi 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @gitbook/react-openapi
 
+## 1.0.2
+
+### Patch Changes
+
+-   bb5c6a4: Support multiple response media types and examples
+-   a3f1fea: Fix display of OpenAPI header description
+-   6157583: Improve Markdown parsing
+-   7419ee7: Show additional fields in OpenAPI block
+-   82cd9f2: Add support for anchor links in OpenAPI blocks
+-   Updated dependencies [6157583]
+    -   @gitbook/openapi-parser@1.0.1
+
 ## 1.0.1
 
 ### Patch Changes

package/dist/OpenAPICodeSample.jsx

@@ -57,7 +57,9 @@ export function OpenAPICodeSample(props) {
             (searchParams.size ? "?".concat(searchParams.toString()) : ''),
         method: data.method,
         body: requestBodyContent
-            ? generateMediaTypeExample(requestBodyContent[1], { onlyRequired: true })
+            ? generateMediaTypeExample(requestBodyContent[1], {
+                omitEmptyAndOptionalProperties: true,
+            })
             : undefined,
         headers: __assign(__assign(__assign({}, getSecurityHeaders(data.securities)), headersObject), (requestBodyContent
             ? {

package/dist/OpenAPIOperation.jsx

@@ -17,12 +17,15 @@ export function OpenAPIOperation(props) {
         icons: context.icons,
         blockKey: context.blockKey,
     };
-    var description = (_a = resolveDescription(operation)) === null || _a === void 0 ? void 0 : _a.trim();
+    var description = resolveDescription(operation);
     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">
+                {operation.summary
+            ? context.renderHeading({
+                deprecated: (_a = operation.deprecated) !== null && _a !== void 0 ? _a : false,
+                title: operation.summary,
+            })
+            : null}
                 {operation.deprecated && <div className="openapi-deprecated">Deprecated</div>}
             </div>
             <div className="openapi-columns">

package/dist/OpenAPIResponse.jsx

@@ -1,11 +1,22 @@
+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);
+};
 import { OpenAPISchemaProperties } from './OpenAPISchema';
-import { resolveDescription } from './utils';
+import { parameterToProperty, resolveDescription } from './utils';
 import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 /**
  * Display an interactive response body.
  */
 export function OpenAPIResponse(props) {
-    var _a, _b, _c;
+    var _a, _b;
     var response = props.response, context = props.context, mediaType = props.mediaType;
     var headers = Object.entries((_a = response.headers) !== null && _a !== void 0 ? _a : {}).map(function (_a) {
         var name = _a[0], header = _a[1];
@@ -17,23 +28,14 @@ export function OpenAPIResponse(props) {
         return null;
     }
     return (<div className="openapi-response-body">
-            {headers.length > 0 ? (<OpenAPIDisclosure context={context} label={'Headers'}>
+            {headers.length > 0 ? (<OpenAPIDisclosure context={context} label="Headers">
                     <OpenAPISchemaProperties properties={headers.map(function (_a) {
-                var _b;
                 var name = _a[0], header = _a[1];
-                return ({
-                    propertyName: name,
-                    schema: (_b = header.schema) !== null && _b !== void 0 ? _b : {},
-                    required: header.required,
-                });
+                return parameterToProperty(__assign({ name: name }, header));
             })} context={context}/>
                 </OpenAPIDisclosure>) : null}
             <div className="openapi-responsebody">
-                <OpenAPISchemaProperties id={"response-".concat(context.blockKey)} properties={[
-            {
-                schema: (_c = mediaType.schema) !== null && _c !== void 0 ? _c : {},
-            },
-        ]} context={context}/>
+                <OpenAPISchemaProperties id={"response-".concat(context.blockKey)} properties={mediaType.schema ? [{ schema: mediaType.schema }] : []} context={context}/>
             </div>
         </div>);
 }

package/dist/OpenAPIResponseExample.jsx

@@ -1,8 +1,8 @@
 import { generateSchemaExample } from './generateSchemaExample';
 import { checkIsReference, createStateKey, resolveDescription } from './utils';
-import { stringifyOpenAPI } from './stringifyOpenAPI';
 import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
 import { InteractiveSection } from './InteractiveSection';
+import { json2xml } from './json2xml';
 /**
  * Display an example of the response content.
  */
@@ -31,78 +31,187 @@ export function OpenAPIResponseExample(props) {
         }
         return Number(a) - Number(b);
     });
-    var examples = responses
+    var tabs = responses
         .map(function (_a) {
-        var key = _a[0], value = _a[1];
-        var responseObject = value;
-        var mediaTypeObject = (function () {
-            var _a;
-            if (!responseObject.content) {
-                return null;
-            }
-            var key = Object.keys(responseObject.content)[0];
-            return ((_a = responseObject.content['application/json']) !== null && _a !== void 0 ? _a : (key ? responseObject.content[key] : null));
-        })();
-        if (!mediaTypeObject) {
+        var key = _a[0], responseObject = _a[1];
+        var description = resolveDescription(responseObject);
+        if (checkIsReference(responseObject)) {
             return {
                 key: key,
                 label: key,
-                description: resolveDescription(responseObject),
+                description: description,
+                body: (<OpenAPIExample example={getExampleFromReference(responseObject)} context={context} syntax="json"/>),
+            };
+        }
+        if (!responseObject.content || Object.keys(responseObject.content).length === 0) {
+            return {
+                key: key,
+                label: key,
+                description: description,
                 body: <OpenAPIEmptyResponseExample />,
             };
         }
-        var example = handleUnresolvedReference((function () {
-            var examples = mediaTypeObject.examples, example = mediaTypeObject.example;
-            if (examples) {
-                var key_1 = Object.keys(examples)[0];
-                if (key_1) {
-                    // @TODO handle multiple examples
-                    var firstExample = examples[key_1];
-                    if (firstExample) {
-                        return firstExample;
-                    }
-                }
-            }
-            if (example) {
-                return { value: example };
-            }
-            var schema = mediaTypeObject.schema;
-            if (!schema) {
-                return null;
-            }
-            return { value: generateSchemaExample(schema) };
-        })());
         return {
             key: key,
             label: key,
             description: resolveDescription(responseObject),
-            body: (example === null || example === void 0 ? void 0 : example.value) ? (<context.CodeBlock code={typeof example.value === 'string'
-                    ? example.value
-                    : stringifyOpenAPI(example.value, null, 2)} syntax="json"/>) : (<OpenAPIEmptyResponseExample />),
+            body: <OpenAPIResponse context={context} content={responseObject.content}/>,
         };
     })
         .filter(function (val) {
         return Boolean(val);
     });
-    if (examples.length === 0) {
+    if (tabs.length === 0) {
         return null;
     }
-    return (<OpenAPITabs stateKey={createStateKey('response-example')} items={examples}>
+    return (<OpenAPITabs stateKey={createStateKey('response-example')} items={tabs}>
             <InteractiveSection header={<OpenAPITabsList />} className="openapi-response-example">
                 <OpenAPITabsPanels />
             </InteractiveSection>
         </OpenAPITabs>);
 }
+function OpenAPIResponse(props) {
+    var context = props.context, content = props.content;
+    var entries = Object.entries(content);
+    var firstEntry = entries[0];
+    if (!firstEntry) {
+        throw new Error('One media type is required');
+    }
+    if (entries.length === 1) {
+        var mediaType = firstEntry[0], mediaTypeObject = firstEntry[1];
+        return (<OpenAPIResponseMediaType context={context} mediaType={mediaType} mediaTypeObject={mediaTypeObject}/>);
+    }
+    var tabs = entries.map(function (entry) {
+        var mediaType = entry[0], mediaTypeObject = entry[1];
+        return {
+            key: mediaType,
+            label: mediaType,
+            body: (<OpenAPIResponseMediaType context={context} mediaType={mediaType} mediaTypeObject={mediaTypeObject}/>),
+        };
+    });
+    return (<OpenAPITabs stateKey={createStateKey('response-media-types')} items={tabs}>
+            <InteractiveSection header={<OpenAPITabsList />} className="openapi-response-media-types">
+                <OpenAPITabsPanels />
+            </InteractiveSection>
+        </OpenAPITabs>);
+}
+function OpenAPIResponseMediaType(props) {
+    var mediaTypeObject = props.mediaTypeObject, mediaType = props.mediaType;
+    var examples = getExamplesFromMediaTypeObject({ mediaTypeObject: mediaTypeObject, mediaType: mediaType });
+    var syntax = getSyntaxFromMediaType(mediaType);
+    var firstExample = examples[0];
+    if (!firstExample) {
+        return <OpenAPIEmptyResponseExample />;
+    }
+    if (examples.length === 1) {
+        return (<OpenAPIExample example={firstExample.example} context={props.context} syntax={syntax}/>);
+    }
+    var tabs = examples.map(function (example) {
+        return {
+            key: example.key,
+            label: example.example.summary || example.key,
+            body: (<OpenAPIExample example={firstExample.example} context={props.context} syntax={syntax}/>),
+        };
+    });
+    return (<OpenAPITabs stateKey={createStateKey('response-media-type-examples')} items={tabs}>
+            <InteractiveSection header={<OpenAPITabsList />} className="openapi-response-media-type-examples">
+                <OpenAPITabsPanels />
+            </InteractiveSection>
+        </OpenAPITabs>);
+}
+/**
+ * Display an example.
+ */
+function OpenAPIExample(props) {
+    var example = props.example, context = props.context, syntax = props.syntax;
+    var code = stringifyExample({ example: example, xml: syntax === 'xml' });
+    if (code === null) {
+        return <OpenAPIEmptyResponseExample />;
+    }
+    return <context.CodeBlock code={code} syntax={syntax}/>;
+}
+function stringifyExample(args) {
+    var example = args.example, xml = args.xml;
+    if (!example.value) {
+        return null;
+    }
+    if (typeof example.value === 'string') {
+        return example.value;
+    }
+    if (xml) {
+        return json2xml(example.value);
+    }
+    return JSON.stringify(example.value, null, 2);
+}
+/**
+ * Get the syntax from a media type.
+ */
+function getSyntaxFromMediaType(mediaType) {
+    if (mediaType.includes('json')) {
+        return 'json';
+    }
+    if (mediaType === 'application/xml') {
+        return 'xml';
+    }
+    return 'text';
+}
+/**
+ * Get examples from a media type object.
+ */
+function getExamplesFromMediaTypeObject(args) {
+    var _a;
+    var _b, _c;
+    var mediaTypeObject = args.mediaTypeObject, mediaType = args.mediaType;
+    if (mediaTypeObject.examples) {
+        return Object.entries(mediaTypeObject.examples).map(function (_a) {
+            var key = _a[0], example = _a[1];
+            return {
+                key: key,
+                example: checkIsReference(example) ? getExampleFromReference(example) : example,
+            };
+        });
+    }
+    if (mediaTypeObject.example) {
+        return [{ key: 'default', example: { value: mediaTypeObject.example } }];
+    }
+    if (mediaTypeObject.schema) {
+        if (mediaType === 'application/xml') {
+            // @TODO normally we should use the name of the schema but we don't have it
+            // fix it when we got the reference name
+            var root = (_c = (_b = mediaTypeObject.schema.xml) === null || _b === void 0 ? void 0 : _b.name) !== null && _c !== void 0 ? _c : 'object';
+            return [
+                {
+                    key: 'default',
+                    example: {
+                        value: (_a = {},
+                            _a[root] = generateSchemaExample(mediaTypeObject.schema, {
+                                xml: mediaType === 'application/xml',
+                            }),
+                            _a),
+                    },
+                },
+            ];
+        }
+        return [
+            {
+                key: 'default',
+                example: { value: generateSchemaExample(mediaTypeObject.schema) },
+            },
+        ];
+    }
+    return [];
+}
+/**
+ * Empty response example.
+ */
 function OpenAPIEmptyResponseExample() {
     return (<pre className="openapi-response-example-empty">
             <p>No body</p>
         </pre>);
 }
-function handleUnresolvedReference(input) {
-    var isReference = checkIsReference(input === null || input === void 0 ? void 0 : input.value);
-    if (isReference) {
-        // If we find a reference that wasn't resolved or needed to be resolved externally, render out the URL
-        return { value: input.value.$ref };
-    }
-    return input;
+/**
+ * Generate an example from a reference object.
+ */
+function getExampleFromReference(ref) {
+    return { summary: 'Unresolved reference', value: { $ref: ref.$ref } };
 }

package/dist/OpenAPISchema.d.ts

@@ -2,8 +2,8 @@ import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import type { OpenAPIClientContext } from './types';
 type CircularRefsIds = Map<OpenAPIV3.SchemaObject, string>;
 export interface OpenAPISchemaPropertyEntry {
-    propertyName?: string;
-    required?: boolean;
+    propertyName?: string | undefined;
+    required?: boolean | undefined;
     schema: OpenAPIV3.SchemaObject;
 }
 /**

package/dist/OpenAPISchema.jsx

@@ -29,7 +29,7 @@ export function OpenAPISchemaProperty(props) {
     var alternatives = parentCircularRef
         ? null
         : getSchemaAlternatives(schema, new Set(circularRefs.keys()));
-    if ((properties && !!properties.length) || schema.type === 'object') {
+    if ((properties && properties.length > 0) || schema.type === 'object') {
         return (<InteractiveSection id={id} className={clsx('openapi-schema', className)}>
                 <OpenAPISchemaPresentation {...props}/>
                 {properties && properties.length > 0 ? (<OpenAPIDisclosure context={context}>
@@ -251,7 +251,7 @@ discriminator) {
     // Otherwise try to infer a nice title
     var type = 'any';
     if (schema.enum) {
-        type = 'enum';
+        type = "".concat(schema.type, " \u00B7 enum");
         // check array AND schema.items as this is sometimes null despite what the type indicates
     }
     else if (schema.type === 'array' && !!schema.items) {
@@ -263,7 +263,7 @@ discriminator) {
     else if (schema.type || schema.properties) {
         type = (_a = schema.type) !== null && _a !== void 0 ? _a : 'object';
         if (schema.format) {
-            type += " ".concat(schema.format);
+            type += " \u00B7 ".concat(schema.format);
         }
     }
     else if ('anyOf' in schema) {
@@ -278,8 +278,17 @@ discriminator) {
     else if ('not' in schema) {
         type = 'not';
     }
+    if (schema.minimum || schema.minLength) {
+        type += " \u00B7 min: ".concat(schema.minimum || schema.minLength);
+    }
+    if (schema.maximum || schema.maxLength) {
+        type += " \u00B7 max: ".concat(schema.maximum || schema.maxLength);
+    }
+    if (schema.default) {
+        type += " \u00B7 default: ".concat(schema.default);
+    }
     if (schema.nullable) {
-        type = "nullable ".concat(type);
+        type = "".concat(type, " | nullable");
     }
     return type;
 }

package/dist/OpenAPISpec.jsx

@@ -1,21 +1,10 @@
 'use client';
-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);
-};
 import { InteractiveSection } from './InteractiveSection';
 import { OpenAPIRequestBody } from './OpenAPIRequestBody';
 import { OpenAPIResponses } from './OpenAPIResponses';
 import { OpenAPISchemaProperties } from './OpenAPISchema';
 import { OpenAPISecurities } from './OpenAPISecurities';
-import { resolveDescription } from './utils';
+import { parameterToProperty } from './utils';
 /**
  * Client component to render the spec for the request and response.
  *
@@ -33,20 +22,7 @@ export function OpenAPISpec(props) {
 
             {parameterGroups.map(function (group) {
             return (<InteractiveSection key={group.key} className="openapi-parameters" header={group.label}>
-                        <OpenAPISchemaProperties properties={group.parameters.map(function (parameter) {
-                    var _a;
-                    var description = resolveDescription(parameter);
-                    return {
-                        propertyName: parameter.name,
-                        schema: __assign({ 
-                            // Description of the parameter is defined at the parameter level
-                            // we use display it if the schema doesn't override it
-                            description: description, example: parameter.example, 
-                            // Deprecated can be defined at the parameter level
-                            deprecated: parameter.deprecated }, ((_a = parameter.schema) !== null && _a !== void 0 ? _a : {})),
-                        required: parameter.required,
-                    };
-                })} context={context}/>
+                        <OpenAPISchemaProperties properties={group.parameters.map(parameterToProperty)} context={context}/>
                     </InteractiveSection>);
         })}
 

package/dist/generateSchemaExample.d.ts

@@ -1,17 +1,16 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
+import { getExampleFromSchema } from '@scalar/oas-utils/spec-getters';
 type JSONValue = string | number | boolean | null | JSONValue[] | {
     [key: string]: JSONValue;
 };
+type ScalarGetExampleFromSchemaOptions = NonNullable<Parameters<typeof getExampleFromSchema>[1]>;
+type GenerateSchemaExampleOptions = Pick<ScalarGetExampleFromSchemaOptions, 'xml' | 'omitEmptyAndOptionalProperties' | 'mode'>;
 /**
  * Generate a JSON example from a schema
  */
-export declare function generateSchemaExample(schema: OpenAPIV3.SchemaObject, options?: {
-    onlyRequired?: boolean;
-}): JSONValue | undefined;
+export declare function generateSchemaExample(schema: OpenAPIV3.SchemaObject, options?: GenerateSchemaExampleOptions): JSONValue | undefined;
 /**
  * Generate an example for a media type.
  */
-export declare function generateMediaTypeExample(mediaType: OpenAPIV3.MediaTypeObject, options?: {
-    onlyRequired?: boolean;
-}): JSONValue | undefined;
+export declare function generateMediaTypeExample(mediaType: OpenAPIV3.MediaTypeObject, options?: GenerateSchemaExampleOptions): JSONValue | undefined;
 export {};

package/dist/generateSchemaExample.js

@@ -1,13 +1,20 @@
+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);
+};
 import { getExampleFromSchema } from '@scalar/oas-utils/spec-getters';
 /**
  * Generate a JSON example from a schema
  */
 export function generateSchemaExample(schema, options) {
-    if (options === void 0) { options = {}; }
-    return getExampleFromSchema(schema, {
-        emptyString: 'text',
-        omitEmptyAndOptionalProperties: options.onlyRequired,
-        variables: {
+    return getExampleFromSchema(schema, __assign({ emptyString: 'text', variables: {
             'date-time': new Date().toISOString(),
             date: new Date().toISOString().split('T')[0],
             email: 'name@gmail.com',
@@ -19,14 +26,12 @@ export function generateSchemaExample(schema, options) {
             binary: 'binary',
             byte: 'Ynl0ZXM=',
             password: 'password',
-        },
-    });
+        } }, options));
 }
 /**
  * Generate an example for a media type.
  */
 export function generateMediaTypeExample(mediaType, options) {
-    if (options === void 0) { options = {}; }
     if (mediaType.example) {
         return mediaType.example;
     }

package/dist/json2xml.d.ts

@@ -0,0 +1,4 @@
+/**
+ * This function converts an object to XML.
+ */
+export declare function json2xml(data: Record<string, any>): string;

package/dist/json2xml.js

@@ -0,0 +1,7 @@
+import { jsXml } from 'json-xml-parse';
+/**
+ * This function converts an object to XML.
+ */
+export function json2xml(data) {
+    return jsXml.toXmlString(data, { beautify: true });
+}