@gitbook/react-openapi 1.0.5 → 1.1.1

package/src/index.ts

@@ -1,4 +1,5 @@
-export * from './resolveOpenAPIOperation';
+export * from './models';
 export * from './OpenAPIOperation';
 export * from './OpenAPIOperationContext';
-export type { OpenAPIOperationData } from './types';
+export * from './resolveOpenAPIOperation';
+export type { OpenAPIModelsData, OpenAPIOperationData } from './types';

package/src/models/OpenAPIModels.tsx

@@ -0,0 +1,89 @@
+import clsx from 'clsx';
+import { OpenAPIDisclosureGroup } from '../OpenAPIDisclosureGroup';
+import { OpenAPIRootSchema } from '../OpenAPISchema';
+import { Section, SectionBody } from '../StaticSection';
+import type { OpenAPIClientContext, OpenAPIContextProps, OpenAPIModelsData } from '../types';
+
+/**
+ * Display OpenAPI Models.
+ */
+export function OpenAPIModels(props: {
+    className?: string;
+    data: OpenAPIModelsData;
+    context: OpenAPIContextProps;
+}) {
+    const { className, data, context } = props;
+    const { models } = data;
+
+    const clientContext: OpenAPIClientContext = {
+        defaultInteractiveOpened: context.defaultInteractiveOpened,
+        icons: context.icons,
+        blockKey: context.blockKey,
+    };
+
+    if (!models.length) {
+        return null;
+    }
+
+    return (
+        <div className={clsx('openapi-models', className)}>
+            <OpenAPIRootModelsSchema models={models} context={clientContext} />
+        </div>
+    );
+}
+
+/**
+ * Root schema for OpenAPI models.
+ * It displays a single model or a disclosure group for multiple models.
+ */
+function OpenAPIRootModelsSchema(props: {
+    models: OpenAPIModelsData['models'];
+    context: OpenAPIClientContext;
+}) {
+    const { models, context } = props;
+
+    // If there is only one model, we show it directly.
+    if (models.length === 1) {
+        const schema = models?.[0]?.schema;
+
+        if (!schema) {
+            return null;
+        }
+
+        return (
+            <Section>
+                <SectionBody>
+                    <OpenAPIRootSchema schema={schema} context={context} />
+                </SectionBody>
+            </Section>
+        );
+    }
+
+    // If there are multiple models, we use a disclosure group to show them all.
+    return (
+        <OpenAPIDisclosureGroup
+            allowsMultipleExpanded
+            icon={context.icons.chevronRight}
+            groups={models.map(({ name, schema }) => ({
+                id: name,
+                label: (
+                    <div className="openapi-response-tab-content" key={`model-${name}`}>
+                        <span className="openapi-response-statuscode">{name}</span>
+                    </div>
+                ),
+                tabs: [
+                    {
+                        id: 'model',
+                        body: (
+                            <Section className="openapi-section-models">
+                                <SectionBody>
+                                    <OpenAPIRootSchema schema={schema} context={context} />
+                                </SectionBody>
+                            </Section>
+                        ),
+                    },
+                ],
+            }))}
+        />
+    );
+}

package/src/models/index.ts

@@ -0,0 +1,2 @@
+export * from './OpenAPIModels';
+export * from './resolveOpenAPIModels';

package/src/models/resolveOpenAPIModels.ts

@@ -0,0 +1,35 @@
+import {
+    type Filesystem,
+    type OpenAPIV3,
+    type OpenAPIV3_1,
+    type OpenAPIV3xDocument,
+    shouldIgnoreEntity,
+} from '@gitbook/openapi-parser';
+import { dereferenceFilesystem } from '../dereference';
+import type { OpenAPIModel, OpenAPIModelsData } from '../types';
+
+//!!TODO: We should return only the models that are used in the block. Still a WIP awaiting future work.
+
+/**
+ * Resolve an OpenAPI models from a file and compile it to a more usable format.
+ * Models are extracted from the OpenAPI components.schemas
+ */
+export async function resolveOpenAPIModels(
+    filesystem: Filesystem<OpenAPIV3xDocument>
+): Promise<OpenAPIModelsData | null> {
+    const schema = await dereferenceFilesystem(filesystem);
+
+    const models = getOpenAPIComponents(schema);
+
+    return { models };
+}
+
+/**
+ * Get OpenAPI components.schemas that are not ignored.
+ */
+function getOpenAPIComponents(schema: OpenAPIV3.Document | OpenAPIV3_1.Document): OpenAPIModel[] {
+    const schemas = schema.components?.schemas ?? {};
+    return Object.entries(schemas)
+        .filter(([, schema]) => !shouldIgnoreEntity(schema))
+        .map(([key, schema]) => ({ name: key, schema }));
+}

package/src/resolveOpenAPIOperation.ts

@@ -1,16 +1,16 @@
 import { fromJSON, toJSON } from 'flatted';
 
-import {
-    type Filesystem,
-    type OpenAPIV3,
-    type OpenAPIV3_1,
-    type OpenAPIV3xDocument,
-    dereference,
+import type {
+    Filesystem,
+    OpenAPIV3,
+    OpenAPIV3_1,
+    OpenAPIV3xDocument,
 } from '@gitbook/openapi-parser';
+import { dereferenceFilesystem } from './dereference';
 import type { OpenAPIOperationData } from './types';
 import { checkIsReference } from './utils';
 
-export { toJSON, fromJSON };
+export { fromJSON, toJSON };
 
 /**
  * Resolve an OpenAPI operation in a file and compile it to a more usable format.
@@ -23,7 +23,7 @@ export async function resolveOpenAPIOperation(
     }
 ): Promise<OpenAPIOperationData | null> {
     const { path, method } = operationDescriptor;
-    const schema = await memoDereferenceFilesystem(filesystem);
+    const schema = await dereferenceFilesystem(filesystem);
     let operation = getOperationByPathAndMethod(schema, path, method);
 
     if (!operation) {
@@ -69,34 +69,6 @@ export async function resolveOpenAPIOperation(
     };
 }
 
-const dereferenceCache = new WeakMap<Filesystem, Promise<OpenAPIV3xDocument>>();
-
-/**
- * Memoized version of `dereferenceSchema`.
- */
-function memoDereferenceFilesystem(filesystem: Filesystem): Promise<OpenAPIV3xDocument> {
-    if (dereferenceCache.has(filesystem)) {
-        return dereferenceCache.get(filesystem) as Promise<OpenAPIV3xDocument>;
-    }
-
-    const promise = dereferenceFilesystem(filesystem);
-    dereferenceCache.set(filesystem, promise);
-    return promise;
-}
-
-/**
- * Dereference an OpenAPI schema.
- */
-async function dereferenceFilesystem(filesystem: Filesystem): Promise<OpenAPIV3xDocument> {
-    const result = await dereference(filesystem);
-
-    if (!result.schema) {
-        throw new Error('Failed to dereference OpenAPI document');
-    }
-
-    return result.schema as OpenAPIV3xDocument;
-}
-
 /**
  * Get a path object from its path.
  */

package/src/types.ts

@@ -55,3 +55,13 @@ export interface OpenAPIOperationData extends OpenAPICustomSpecProperties {
     /** Securities that should be used for this operation */
     securities: [string, OpenAPIV3.SecuritySchemeObject][];
 }
+
+export type OpenAPIModel = {
+    name: string;
+    schema: OpenAPIV3.SchemaObject;
+};
+
+export interface OpenAPIModelsData {
+    /** Components schemas to be used for models */
+    models: OpenAPIModel[];
+}

package/src/utils.ts

@@ -1,4 +1,5 @@
 import type { AnyObject, OpenAPIV3, OpenAPIV3_1 } from '@gitbook/openapi-parser';
+import { stringifyOpenAPI } from './stringifyOpenAPI';
 
 export function checkIsReference(
     input: unknown
@@ -10,11 +11,19 @@ export function createStateKey(key: string, scope?: string) {
     return scope ? `${scope}_${key}` : key;
 }
 
+/**
+ * Check if an object has a description. Either at the root level or in items.
+ */
+function hasDescription(object: AnyObject) {
+    return 'description' in object || 'x-gitbook-description-html' in object;
+}
+
 /**
  * Resolve the description of an object.
  */
 export function resolveDescription(object: OpenAPIV3.SchemaObject | AnyObject) {
-    if ('items' in object && object.items) {
+    // If the object has items and has a description, we resolve the description from items
+    if ('items' in object && typeof object.items === 'object' && hasDescription(object.items)) {
         return resolveDescription(object.items);
     }
 
@@ -42,17 +51,25 @@ export function extractDescriptions(object: AnyObject) {
 /**
  * Resolve the first example from an object.
  */
-export function resolveFirstExample(object: AnyObject) {
+export function resolveFirstExample(object: AnyObject): string | undefined {
     if ('examples' in object && typeof object.examples === 'object' && object.examples) {
         const keys = Object.keys(object.examples);
         const firstKey = keys[0];
         if (firstKey && object.examples[firstKey]) {
-            return object.examples[firstKey];
+            return formatExample(object.examples[firstKey]);
         }
     }
-    if ('example' in object && object.example !== undefined) {
-        return object.example;
+
+    // Resolve top level example first
+    if (shouldDisplayExample(object)) {
+        return formatExample(object.example);
     }
+
+    // Resolve example from items if it exists
+    if (object.items && typeof object.items === 'object') {
+        return formatExample(object.items.example);
+    }
+
     return undefined;
 }
 
@@ -98,3 +115,34 @@ export function parameterToProperty(
         required: parameter.required,
     };
 }
+
+/**
+ * Format the example of a schema.
+ */
+function formatExample(example: unknown): string {
+    if (typeof example === 'string') {
+        return example
+            .replace(/\n/g, ' ') // Replace newlines with spaces
+            .replace(/\s+/g, ' ') // Collapse multiple spaces/newlines into a single space
+            .replace(/([\{\}:,])\s+/g, '$1 ') // Ensure a space after {, }, :, and ,
+            .replace(/\s+([\{\}:,])/g, ' $1') // Ensure a space before {, }, :, and ,
+            .trim();
+    }
+
+    return stringifyOpenAPI(example);
+}
+
+/**
+ * Check if an example should be displayed.
+ */
+function shouldDisplayExample(schema: OpenAPIV3.SchemaObject): boolean {
+    return (
+        (typeof schema.example === 'string' && !!schema.example) ||
+        typeof schema.example === 'number' ||
+        typeof schema.example === 'boolean' ||
+        (Array.isArray(schema.example) && schema.example.length > 0) ||
+        (typeof schema.example === 'object' &&
+            schema.example !== null &&
+            Object.keys(schema.example).length > 0)
+    );
+}