@gitbook/react-openapi 1.0.0 → 1.0.2

package/src/OpenAPIResponseExample.tsx

@@ -1,10 +1,10 @@
 import type { OpenAPIV3 } from '@gitbook/openapi-parser';
 import { generateSchemaExample } from './generateSchemaExample';
 import type { OpenAPIContextProps, OpenAPIOperationData } from './types';
-import { checkIsReference, noReference, resolveDescription } from './utils';
-import { stringifyOpenAPI } from './stringifyOpenAPI';
+import { checkIsReference, createStateKey, resolveDescription } from './utils';
 import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
 import { InteractiveSection } from './InteractiveSection';
+import { json2xml } from './json2xml';
 
 /**
  * Display an example of the response content.
@@ -38,84 +38,51 @@ export function OpenAPIResponseExample(props: {
         return Number(a) - Number(b);
     });
 
-    const examples = responses
-        .map(([key, value]) => {
-            const responseObject = noReference(value);
-            const mediaTypeObject = (() => {
-                if (!responseObject.content) {
-                    return null;
-                }
-                const key = Object.keys(responseObject.content)[0];
-                return (
-                    responseObject.content['application/json'] ??
-                    (key ? responseObject.content[key] : null)
-                );
-            })();
-
-            if (!mediaTypeObject) {
+    const tabs = responses
+        .map(([key, responseObject]) => {
+            const description = resolveDescription(responseObject);
+
+            if (checkIsReference(responseObject)) {
                 return {
                     key: key,
                     label: key,
-                    description: resolveDescription(responseObject),
-                    body: <OpenAPIEmptyResponseExample />,
+                    description,
+                    body: (
+                        <OpenAPIExample
+                            example={getExampleFromReference(responseObject)}
+                            context={context}
+                            syntax="json"
+                        />
+                    ),
                 };
             }
 
-            const example = handleUnresolvedReference(
-                (() => {
-                    const { examples, example } = mediaTypeObject;
-                    if (examples) {
-                        const key = Object.keys(examples)[0];
-                        if (key) {
-                            // @TODO handle multiple examples
-                            const firstExample = noReference(examples[key]);
-                            if (firstExample) {
-                                return firstExample;
-                            }
-                        }
-                    }
-
-                    if (example) {
-                        return { value: example };
-                    }
-
-                    const schema = noReference(mediaTypeObject.schema);
-                    if (!schema) {
-                        return null;
-                    }
-
-                    return { value: generateSchemaExample(schema) };
-                })(),
-            );
+            if (!responseObject.content || Object.keys(responseObject.content).length === 0) {
+                return {
+                    key: key,
+                    label: key,
+                    description,
+                    body: <OpenAPIEmptyResponseExample />,
+                };
+            }
 
             return {
                 key: key,
                 label: key,
                 description: resolveDescription(responseObject),
-                body: 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((val): val is { key: string; label: string; body: any; description: string } =>
             Boolean(val),
         );
 
-    if (examples.length === 0) {
+    if (tabs.length === 0) {
         return null;
     }
 
     return (
-        <OpenAPITabs items={examples}>
+        <OpenAPITabs stateKey={createStateKey('response-example')} items={tabs}>
             <InteractiveSection header={<OpenAPITabsList />} className="openapi-response-example">
                 <OpenAPITabsPanels />
             </InteractiveSection>
@@ -123,6 +90,212 @@ export function OpenAPIResponseExample(props: {
     );
 }
 
+function OpenAPIResponse(props: {
+    context: OpenAPIContextProps;
+    content: {
+        [media: string]: OpenAPIV3.MediaTypeObject;
+    };
+}) {
+    const { context, content } = props;
+
+    const entries = Object.entries(content);
+    const firstEntry = entries[0];
+
+    if (!firstEntry) {
+        throw new Error('One media type is required');
+    }
+
+    if (entries.length === 1) {
+        const [mediaType, mediaTypeObject] = firstEntry;
+        return (
+            <OpenAPIResponseMediaType
+                context={context}
+                mediaType={mediaType}
+                mediaTypeObject={mediaTypeObject}
+            />
+        );
+    }
+
+    const tabs = entries.map((entry) => {
+        const [mediaType, mediaTypeObject] = entry;
+        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: {
+    mediaTypeObject: OpenAPIV3.MediaTypeObject;
+    mediaType: string;
+    context: OpenAPIContextProps;
+}) {
+    const { mediaTypeObject, mediaType } = props;
+    const examples = getExamplesFromMediaTypeObject({ mediaTypeObject, mediaType });
+    const syntax = getSyntaxFromMediaType(mediaType);
+    const firstExample = examples[0];
+
+    if (!firstExample) {
+        return <OpenAPIEmptyResponseExample />;
+    }
+
+    if (examples.length === 1) {
+        return (
+            <OpenAPIExample
+                example={firstExample.example}
+                context={props.context}
+                syntax={syntax}
+            />
+        );
+    }
+
+    const tabs = examples.map((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: {
+    example: OpenAPIV3.ExampleObject;
+    context: OpenAPIContextProps;
+    syntax: string;
+}) {
+    const { example, context, syntax } = props;
+    const code = stringifyExample({ example, xml: syntax === 'xml' });
+
+    if (code === null) {
+        return <OpenAPIEmptyResponseExample />;
+    }
+
+    return <context.CodeBlock code={code} syntax={syntax} />;
+}
+
+function stringifyExample(args: { example: OpenAPIV3.ExampleObject; xml: boolean }): string | null {
+    const { example, xml } = args;
+
+    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: string): string {
+    if (mediaType.includes('json')) {
+        return 'json';
+    }
+
+    if (mediaType === 'application/xml') {
+        return 'xml';
+    }
+
+    return 'text';
+}
+
+/**
+ * Get examples from a media type object.
+ */
+function getExamplesFromMediaTypeObject(args: {
+    mediaType: string;
+    mediaTypeObject: OpenAPIV3.MediaTypeObject;
+}): { key: string; example: OpenAPIV3.ExampleObject }[] {
+    const { mediaTypeObject, mediaType } = args;
+    if (mediaTypeObject.examples) {
+        return Object.entries(mediaTypeObject.examples).map(([key, example]) => {
+            return {
+                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
+            const root = mediaTypeObject.schema.xml?.name ?? 'object';
+            return [
+                {
+                    key: 'default',
+                    example: {
+                        value: {
+                            [root]: generateSchemaExample(mediaTypeObject.schema, {
+                                xml: mediaType === 'application/xml',
+                            }),
+                        },
+                    },
+                },
+            ];
+        }
+        return [
+            {
+                key: 'default',
+                example: { value: generateSchemaExample(mediaTypeObject.schema) },
+            },
+        ];
+    }
+    return [];
+}
+
+/**
+ * Empty response example.
+ */
 function OpenAPIEmptyResponseExample() {
     return (
         <pre className="openapi-response-example-empty">
@@ -131,15 +304,9 @@ function OpenAPIEmptyResponseExample() {
     );
 }
 
-function handleUnresolvedReference(
-    input: OpenAPIV3.ExampleObject | null,
-): OpenAPIV3.ExampleObject | null {
-    const isReference = checkIsReference(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: OpenAPIV3.ReferenceObject): OpenAPIV3.ExampleObject {
+    return { summary: 'Unresolved reference', value: { $ref: ref.$ref } };
 }

package/src/OpenAPIResponses.tsx

@@ -1,5 +1,4 @@
 import type { OpenAPIV3, OpenAPIV3_1 } from '@gitbook/openapi-parser';
-import { createStateKey, resolveDescription } from './utils';
 import { OpenAPIResponse } from './OpenAPIResponse';
 import { OpenAPIClientContext } from './types';
 import { InteractiveSection } from './InteractiveSection';
@@ -16,18 +15,14 @@ export function OpenAPIResponses(props: {
     const { responses, context } = props;
 
     return (
-        <InteractiveSection
-            stateKey={createStateKey('response', context.blockKey)}
-            header="Responses"
-            className="openapi-responses"
-        >
+        <InteractiveSection header="Responses" className="openapi-responses">
             <OpenAPIDisclosureGroup
                 allowsMultipleExpanded
                 icon={context.icons.chevronRight}
                 groups={Object.entries(responses).map(
                     ([statusCode, response]: [string, OpenAPIV3.ResponseObject]) => {
                         const content = Object.entries(response.content ?? {});
-                        const description = resolveDescription(response);
+                        const description = response.description;
 
                         return {
                             id: statusCode,

package/src/OpenAPISchema.tsx

@@ -5,7 +5,7 @@ import { useId } from 'react';
 import { InteractiveSection } from './InteractiveSection';
 import { Markdown } from './Markdown';
 import type { OpenAPIClientContext } from './types';
-import { checkIsReference, noReference, resolveDescription } from './utils';
+import { checkIsReference, resolveDescription } from './utils';
 import { stringifyOpenAPI } from './stringifyOpenAPI';
 import { OpenAPISchemaName } from './OpenAPISchemaName';
 import { OpenAPIDisclosure } from './OpenAPIDisclosure';
@@ -13,8 +13,8 @@ import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 type CircularRefsIds = Map<OpenAPIV3.SchemaObject, string>;
 
 export interface OpenAPISchemaPropertyEntry {
-    propertyName?: string;
-    required?: boolean;
+    propertyName?: string | undefined;
+    required?: boolean | undefined;
     schema: OpenAPIV3.SchemaObject;
 }
 
@@ -47,19 +47,19 @@ export function OpenAPISchemaProperty(
         ? 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} />
-                <OpenAPIDisclosure context={context}>
-                    {properties && properties.length > 0 ? (
+                {properties && properties.length > 0 ? (
+                    <OpenAPIDisclosure context={context}>
                         <OpenAPISchemaProperties
                             properties={properties}
                             circularRefs={circularRefs}
                             context={context}
                         />
-                    ) : null}
-                </OpenAPIDisclosure>
+                    </OpenAPIDisclosure>
+                ) : null}
             </InteractiveSection>
         );
     }
@@ -70,7 +70,7 @@ export function OpenAPISchemaProperty(
                 <OpenAPISchemaPresentation {...props} />
                 {alternatives[0].map((alternative, index) => (
                     <OpenAPISchemaAlternative
-                        key={index}
+                        key={`alternative-${index}`}
                         schema={alternative}
                         circularRefs={circularRefs}
                         context={context}
@@ -278,9 +278,9 @@ export function OpenAPISchemaPresentation(props: OpenAPISchemaPropertyEntry) {
 function getSchemaProperties(schema: OpenAPIV3.SchemaObject): null | OpenAPISchemaPropertyEntry[] {
     if (schema.allOf) {
         return schema.allOf.reduce((acc, subSchema) => {
-            const properties = getSchemaProperties(noReference(subSchema)) ?? [
+            const properties = getSchemaProperties(subSchema) ?? [
                 {
-                    schema: noReference(subSchema),
+                    schema: subSchema,
                 },
             ];
             return [...acc, ...properties];
@@ -289,7 +289,7 @@ function getSchemaProperties(schema: OpenAPIV3.SchemaObject): null | OpenAPISche
 
     // 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 items = schema.items;
         const itemProperties = getSchemaProperties(items);
         if (itemProperties) {
             return itemProperties;
@@ -307,12 +307,7 @@ function getSchemaProperties(schema: OpenAPIV3.SchemaObject): null | OpenAPISche
         const result: OpenAPISchemaPropertyEntry[] = [];
 
         if (schema.properties) {
-            Object.entries(schema.properties).forEach(([propertyName, rawPropertySchema]) => {
-                const isReference = checkIsReference(rawPropertySchema);
-                const propertySchema: OpenAPIV3.SchemaObject = isReference
-                    ? { propertyName }
-                    : rawPropertySchema;
-
+            Object.entries(schema.properties).forEach(([propertyName, propertySchema]) => {
                 result.push({
                     propertyName,
                     required: Array.isArray(schema.required)
@@ -324,7 +319,7 @@ function getSchemaProperties(schema: OpenAPIV3.SchemaObject): null | OpenAPISche
         }
 
         if (schema.additionalProperties) {
-            const additionalProperties = noReference(schema.additionalProperties);
+            const additionalProperties = schema.additionalProperties;
 
             result.push({
                 propertyName: 'Other properties',
@@ -348,17 +343,11 @@ export function getSchemaAlternatives(
     const downAncestors = new Set(ancestors).add(schema);
 
     if (schema.anyOf) {
-        return [
-            flattenAlternatives('anyOf', schema.anyOf.map(noReference), downAncestors),
-            noReference(schema.discriminator),
-        ];
+        return [flattenAlternatives('anyOf', schema.anyOf, downAncestors), schema.discriminator];
     }
 
     if (schema.oneOf) {
-        return [
-            flattenAlternatives('oneOf', schema.oneOf.map(noReference), downAncestors),
-            noReference(schema.discriminator),
-        ];
+        return [flattenAlternatives('oneOf', schema.oneOf, downAncestors), schema.discriminator];
     }
 
     if (schema.allOf) {
@@ -396,8 +385,8 @@ export function getSchemaTitle(
 
     // Try using the discriminator
     if (discriminator?.propertyName && schema.properties) {
-        const discriminatorProperty = noReference(schema.properties[discriminator.propertyName]);
-        if (discriminatorProperty) {
+        const discriminatorProperty = schema.properties[discriminator.propertyName];
+        if (discriminatorProperty && !checkIsReference(discriminatorProperty)) {
             if (discriminatorProperty.enum) {
                 return discriminatorProperty.enum.map((value) => value.toString()).join(' | ');
             }
@@ -408,17 +397,17 @@ export function getSchemaTitle(
     let type = 'any';
 
     if (schema.enum) {
-        type = 'enum';
+        type = `${schema.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 = `${getSchemaTitle(noReference(schema.items))}[]`;
+        type = `${getSchemaTitle(schema.items)}[]`;
     } else if (Array.isArray(schema.type)) {
         type = schema.type.join(' | ');
     } else if (schema.type || schema.properties) {
         type = schema.type ?? 'object';
 
         if (schema.format) {
-            type += ` ${schema.format}`;
+            type += ` · ${schema.format}`;
         }
     } else if ('anyOf' in schema) {
         type = 'any of';
@@ -430,8 +419,20 @@ export function getSchemaTitle(
         type = 'not';
     }
 
+    if (schema.minimum || schema.minLength) {
+        type += ` · min: ${schema.minimum || schema.minLength}`;
+    }
+
+    if (schema.maximum || schema.maxLength) {
+        type += ` · max: ${schema.maximum || schema.maxLength}`;
+    }
+
+    if (schema.default) {
+        type += ` · default: ${schema.default}`;
+    }
+
     if (schema.nullable) {
-        type = `nullable ${type}`;
+        type = `${type} | nullable`;
     }
 
     return type;

package/src/OpenAPISpec.tsx

@@ -8,7 +8,7 @@ import { OpenAPIResponses } from './OpenAPIResponses';
 import { OpenAPISchemaProperties } from './OpenAPISchema';
 import { OpenAPISecurities } from './OpenAPISecurities';
 import type { OpenAPIClientContext, OpenAPIOperationData } from './types';
-import { noReference, resolveDescription } from './utils';
+import { parameterToProperty } from './utils';
 
 /**
  * Client component to render the spec for the request and response.
@@ -38,22 +38,7 @@ export function OpenAPISpec(props: { data: OpenAPIOperationData; context: OpenAP
                         header={group.label}
                     >
                         <OpenAPISchemaProperties
-                            properties={group.parameters.map((parameter) => {
-                                const description = resolveDescription(parameter);
-                                return {
-                                    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: description,
-                                        example: parameter.example,
-                                        // Deprecated can be defined at the parameter level
-                                        deprecated: parameter.deprecated,
-                                        ...(noReference(parameter.schema) ?? {}),
-                                    },
-                                    required: parameter.required,
-                                };
-                            })}
+                            properties={group.parameters.map(parameterToProperty)}
                             context={context}
                         />
                     </InteractiveSection>
@@ -61,13 +46,10 @@ export function OpenAPISpec(props: { data: OpenAPIOperationData; context: OpenAP
             })}
 
             {operation.requestBody ? (
-                <OpenAPIRequestBody
-                    requestBody={noReference(operation.requestBody)}
-                    context={context}
-                />
+                <OpenAPIRequestBody requestBody={operation.requestBody} context={context} />
             ) : null}
             {operation.responses ? (
-                <OpenAPIResponses responses={noReference(operation.responses)} context={context} />
+                <OpenAPIResponses responses={operation.responses} context={context} />
             ) : null}
         </>
     );