Support for OpenAPI references (#2813)

nolannbiron · web-flow · commit 883d10acf84b · 2025-02-07T11:46:23.000+01:00
diff --git a/.changeset/six-trainers-bathe.md b/.changeset/six-trainers-bathe.md
@@ -0,0 +1,5 @@
+---
+'@gitbook/react-openapi': patch
+---
+
+Support for OpenAPI references
diff --git a/packages/react-openapi/src/OpenAPICodeSample.tsx b/packages/react-openapi/src/OpenAPICodeSample.tsx
@@ -6,9 +6,10 @@ import { generateMediaTypeExample, generateSchemaExample } from './generateSchem
 import { InteractiveSection } from './InteractiveSection';
 import { getServersURL } from './OpenAPIServerURL';
 import { OpenAPIContextProps } from './types';
-import { noReference } from './utils';
 import { stringifyOpenAPI } from './stringifyOpenAPI';
 import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
+import { OpenAPIV3 } from '@scalar/openapi-types';
+import { checkIsReference } from './utils';
 
 /**
  * Display code samples to execute the operation.
@@ -23,24 +24,19 @@ export function OpenAPICodeSample(props: {
     const searchParams = new URLSearchParams();
     const headersObject: { [k: string]: string } = {};
 
-    data.operation.parameters?.forEach((rawParam) => {
-        const param = noReference(rawParam);
+    data.operation.parameters?.forEach((param) => {
         if (!param) {
             return;
         }
 
         if (param.in === 'header' && param.required) {
-            const example = param.schema
-                ? generateSchemaExample(noReference(param.schema))
-                : undefined;
+            const example = param.schema ? generateSchemaExample(param.schema) : undefined;
             if (example !== undefined && param.name) {
                 headersObject[param.name] =
                     typeof example !== 'string' ? stringifyOpenAPI(example) : example;
             }
         } else if (param.in === 'query' && param.required) {
-            const example = param.schema
-                ? generateSchemaExample(noReference(param.schema))
-                : undefined;
+            const example = param.schema ? generateSchemaExample(param.schema) : undefined;
             if (example !== undefined && param.name) {
                 searchParams.append(
                     param.name,
@@ -50,7 +46,9 @@ export function OpenAPICodeSample(props: {
         }
     });
 
-    const requestBody = noReference(data.operation.requestBody);
+    const requestBody = !checkIsReference(data.operation.requestBody)
+        ? data.operation.requestBody
+        : undefined;
     const requestBodyContentEntries = requestBody?.content
         ? Object.entries(requestBody.content)
         : undefined;
diff --git a/packages/react-openapi/src/OpenAPIRequestBody.tsx b/packages/react-openapi/src/OpenAPIRequestBody.tsx
@@ -2,19 +2,23 @@ import * as React from 'react';
 
 import { OpenAPIV3 } from '@scalar/openapi-types';
 import { OpenAPIRootSchema } from './OpenAPISchema';
-import { noReference } from './utils';
 import { OpenAPIClientContext } from './types';
 import { InteractiveSection } from './InteractiveSection';
+import { checkIsReference } from './utils';
 
 /**
  * Display an interactive request body.
  */
 export function OpenAPIRequestBody(props: {
-    requestBody: OpenAPIV3.RequestBodyObject;
+    requestBody: OpenAPIV3.RequestBodyObject | OpenAPIV3.ReferenceObject;
     context: OpenAPIClientContext;
 }) {
     const { requestBody, context } = props;
 
+    if (checkIsReference(requestBody)) {
+        return null;
+    }
+
     return (
         <InteractiveSection
             header="Body"
@@ -26,7 +30,7 @@ export function OpenAPIRequestBody(props: {
                         label: contentType,
                         body: (
                             <OpenAPIRootSchema
-                                schema={noReference(mediaTypeObject.schema) ?? {}}
+                                schema={mediaTypeObject.schema ?? {}}
                                 context={context}
                             />
                         ),
diff --git a/packages/react-openapi/src/OpenAPIResponse.tsx b/packages/react-openapi/src/OpenAPIResponse.tsx
@@ -1,7 +1,6 @@
 import classNames from 'classnames';
 import { OpenAPIV3 } from '@scalar/openapi-types';
 import { OpenAPISchemaProperties } from './OpenAPISchema';
-import { checkIsReference, noReference } from './utils';
 import { OpenAPIClientContext } from './types';
 import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 
@@ -15,7 +14,7 @@ export function OpenAPIResponse(props: {
 }) {
     const { response, context, mediaType } = props;
     const headers = Object.entries(response.headers ?? {}).map(
-        ([name, header]) => [name, noReference(header) ?? {}] as const,
+        ([name, header]) => [name, header ?? {}] as const,
     );
     const content = Object.entries(mediaType.schema ?? {});
 
@@ -30,7 +29,7 @@ export function OpenAPIResponse(props: {
                     <OpenAPISchemaProperties
                         properties={headers.map(([name, header]) => ({
                             propertyName: name,
-                            schema: noReference(header.schema) ?? {},
+                            schema: header.schema ?? {},
                             required: header.required,
                         }))}
                         context={context}
@@ -42,7 +41,7 @@ export function OpenAPIResponse(props: {
                     id={`response-${context.blockKey}`}
                     properties={[
                         {
-                            schema: handleUnresolvedReference(mediaType.schema) ?? {},
+                            schema: mediaType.schema ?? {},
                         },
                     ]}
                     context={context}
@@ -51,17 +50,3 @@ export function OpenAPIResponse(props: {
         </div>
     );
 }
-
-function handleUnresolvedReference(
-    input: OpenAPIV3.SchemaObject | OpenAPIV3.ReferenceObject | undefined,
-): OpenAPIV3.SchemaObject {
-    const isReference = checkIsReference(input);
-
-    if (isReference || input === undefined) {
-        // If we find a reference that wasn't resolved or needed to be resolved externally, do not try to render it.
-        // Instead we render `any`
-        return {};
-    }
-
-    return input;
-}
diff --git a/packages/react-openapi/src/OpenAPIResponseExample.tsx b/packages/react-openapi/src/OpenAPIResponseExample.tsx
@@ -1,7 +1,6 @@
 import { OpenAPIOperationData } from './fetchOpenAPIOperation';
 import { generateSchemaExample } from './generateSchemaExample';
 import { OpenAPIContextProps } from './types';
-import { checkIsReference, noReference } from './utils';
 import { stringifyOpenAPI } from './stringifyOpenAPI';
 import { OpenAPIV3 } from '@scalar/openapi-types';
 import { OpenAPITabs, OpenAPITabsList, OpenAPITabsPanels } from './OpenAPITabs';
@@ -41,7 +40,7 @@ export function OpenAPIResponseExample(props: {
 
     const examples = responses
         .map(([key, value]) => {
-            const responseObject = noReference(value);
+            const responseObject = value;
             const mediaTypeObject = (() => {
                 if (!responseObject.content) {
                     return null;
@@ -61,30 +60,28 @@ export function OpenAPIResponseExample(props: {
                 };
             }
 
-            const example = handleUnresolvedReference(
-                (() => {
-                    const { examples, example } = mediaTypeObject;
-                    if (examples) {
-                        const firstKey = Object.keys(examples)[0];
-                        // @TODO handle multiple examples
-                        const firstExample = noReference(examples[firstKey]);
-                        if (firstExample) {
-                            return firstExample;
-                        }
+            const example: OpenAPIV3.ExampleObject | null = (() => {
+                const { examples, example } = mediaTypeObject;
+                if (examples) {
+                    const firstKey = Object.keys(examples)[0];
+                    // @TODO handle multiple examples
+                    const firstExample = examples[firstKey];
+                    if (firstExample) {
+                        return firstExample;
                     }
+                }
 
-                    if (example) {
-                        return { value: example };
-                    }
+                if (example) {
+                    return { value: example };
+                }
 
-                    const schema = noReference(mediaTypeObject.schema);
-                    if (!schema) {
-                        return null;
-                    }
+                const schema = mediaTypeObject.schema;
+                if (!schema) {
+                    return null;
+                }
 
-                    return { value: generateSchemaExample(schema) };
-                })(),
-            );
+                return { value: generateSchemaExample(schema) };
+            })();
 
             return {
                 key: key,
@@ -128,16 +125,3 @@ function OpenAPIEmptyResponseExample() {
         </pre>
     );
 }
-
-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;
-}
diff --git a/packages/react-openapi/src/OpenAPIResponses.tsx b/packages/react-openapi/src/OpenAPIResponses.tsx
@@ -1,14 +1,12 @@
 import * as React from 'react';
 import classNames from 'classnames';
-import { createStateKey, noReference } from './utils';
+import { createStateKey } from './utils';
 import { OpenAPIResponse } from './OpenAPIResponse';
 import { OpenAPIClientContext } from './types';
 import { InteractiveSection } from './InteractiveSection';
 import { OpenAPIV3, OpenAPIV3_1 } from '@scalar/openapi-types';
 import { OpenAPIDisclosureGroup } from './OpenAPIDisclosureGroup';
 import { Markdown } from './Markdown';
-import { OpenAPIRootSchema, OpenAPISchemaProperties, OpenAPISchemaProperty } from './OpenAPISchema';
-import { OpenAPIDisclosure } from './OpenAPIDisclosure';
 
 /**
  * Display an interactive response body.
diff --git a/packages/react-openapi/src/OpenAPISchema.tsx b/packages/react-openapi/src/OpenAPISchema.tsx
@@ -5,10 +5,10 @@ import React, { useId } from 'react';
 import { InteractiveSection } from './InteractiveSection';
 import { Markdown } from './Markdown';
 import { OpenAPIClientContext } from './types';
-import { checkIsReference, noReference } from './utils';
 import { stringifyOpenAPI } from './stringifyOpenAPI';
 import { OpenAPISchemaName } from './OpenAPISchemaName';
 import { OpenAPIDisclosure } from './OpenAPIDisclosure';
+import { checkIsReference } from './utils';
 
 type CircularRefsIds = Map<OpenAPIV3.SchemaObject, string>;
 
@@ -275,9 +275,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];
@@ -286,7 +286,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;
@@ -304,12 +304,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)
@@ -321,7 +316,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',
@@ -345,17 +340,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) {
@@ -393,8 +382,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,7 +397,7 @@ export function getSchemaTitle(
         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) {
diff --git a/packages/react-openapi/src/OpenAPISpec.tsx b/packages/react-openapi/src/OpenAPISpec.tsx
@@ -2,14 +2,13 @@
 
 import { OpenAPI } from '@scalar/openapi-types';
 
-import { OpenAPIOperationData, fromJSON } from './fetchOpenAPIOperation';
+import { OpenAPIOperationData } from './fetchOpenAPIOperation';
 import { InteractiveSection } from './InteractiveSection';
 import { OpenAPIRequestBody } from './OpenAPIRequestBody';
 import { OpenAPIResponses } from './OpenAPIResponses';
 import { OpenAPISchemaProperties } from './OpenAPISchema';
 import { OpenAPISecurities } from './OpenAPISecurities';
 import { OpenAPIClientContext } from './types';
-import { noReference } from './utils';
 
 /**
  * Client component to render the spec for the request and response.
@@ -47,7 +46,7 @@ export function OpenAPISpec(props: { data: OpenAPIOperationData; context: OpenAP
                                 example: parameter.example,
                                 // Deprecated can be defined at the parameter level
                                 deprecated: parameter.deprecated,
-                                ...(noReference(parameter.schema) ?? {}),
+                                ...(parameter.schema ?? {}),
                             },
                             required: parameter.required,
                         }))}
@@ -57,13 +56,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}
         </>
     );
diff --git a/packages/react-openapi/src/fetchOpenAPIOperation.ts b/packages/react-openapi/src/fetchOpenAPIOperation.ts
diff --git a/packages/react-openapi/src/generateSchemaExample.ts b/packages/react-openapi/src/generateSchemaExample.ts
diff --git a/packages/react-openapi/src/parser/fetchUrls.ts b/packages/react-openapi/src/parser/fetchUrls.ts
diff --git a/packages/react-openapi/src/utils.ts b/packages/react-openapi/src/utils.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@gitbook/react-openapi': patch
 +---
++
 +Support for OpenAPI references