Rename OpenAPIModels to OpenAPISchemas (#2946)

.changeset/healthy-paws-flash.md

@@ -0,0 +1,6 @@
+---
+'@gitbook/react-openapi': patch
+'gitbook': patch
+---
+
+Rename OpenAPIModels to OpenAPISchemas

packages/gitbook/src/components/DocumentView/OpenAPI/style.css

@@ -3,7 +3,7 @@
     @apply flex-1 flex flex-col gap-4 mb-14;
 }
 
-.openapi-models {
+.openapi-schemas {
     @apply flex flex-col mb-14 flex-1;
 }
 
@@ -620,10 +620,10 @@
     @apply space-y-2.5;
 }
 
-.openapi-section-models {
+.openapi-section-schemas {
     @apply border border-tint-subtle rounded-lg;
 }
 
-.openapi-section-models > .openapi-section-body > .openapi-schema-properties > .openapi-schema {
+.openapi-section-schemas > .openapi-section-body > .openapi-schema-properties > .openapi-schema {
     @apply p-2.5;
 }

packages/gitbook/src/lib/openapi/resolveOpenAPISchemasBlock.ts

@@ -1,35 +1,35 @@
 import { fetchOpenAPIFilesystem } from '@/lib/openapi/fetch';
 import type { ResolveOpenAPIBlockResult } from '@/lib/openapi/types';
 import { OpenAPIParseError } from '@gitbook/openapi-parser';
-import { type OpenAPIModelsData, resolveOpenAPIModels } from '@gitbook/react-openapi';
+import { type OpenAPISchemasData, resolveOpenAPISchemas } from '@gitbook/react-openapi';
 import type { AnyOpenAPIBlock, ResolveOpenAPIBlockArgs } from './types';
 
-type ResolveOpenAPIModelsBlockResult = ResolveOpenAPIBlockResult<OpenAPIModelsData>;
+type ResolveOpenAPISchemasBlockResult = ResolveOpenAPIBlockResult<OpenAPISchemasData>;
 
-const weakmap = new WeakMap<AnyOpenAPIBlock, Promise<ResolveOpenAPIModelsBlockResult>>();
+const weakmap = new WeakMap<AnyOpenAPIBlock, Promise<ResolveOpenAPISchemasBlockResult>>();
 
 /**
  * Cache the result of resolving an OpenAPI block.
  * It is important because the resolve is called in sections and in the block itself.
  */
-export function resolveOpenAPIModelsBlock(
+export function resolveOpenAPISchemasBlock(
     args: ResolveOpenAPIBlockArgs
-): Promise<ResolveOpenAPIModelsBlockResult> {
+): Promise<ResolveOpenAPISchemasBlockResult> {
     if (weakmap.has(args.block)) {
         return weakmap.get(args.block)!;
     }
 
-    const result = baseResolveOpenAPIModelsBlock(args);
+    const result = baseResolveOpenAPISchemasBlock(args);
     weakmap.set(args.block, result);
     return result;
 }
 
 /**
- * Resolve OpenAPI models block.
+ * Resolve OpenAPI schemas block.
  */
-async function baseResolveOpenAPIModelsBlock(
+async function baseResolveOpenAPISchemasBlock(
     args: ResolveOpenAPIBlockArgs
-): Promise<ResolveOpenAPIModelsBlockResult> {
+): Promise<ResolveOpenAPISchemasBlockResult> {
     const { context, block } = args;
     if (!block.data.path || !block.data.method) {
         return { data: null, specUrl: null };
@@ -42,7 +42,7 @@ async function baseResolveOpenAPIModelsBlock(
             return { data: null, specUrl: null };
         }
 
-        const data = await resolveOpenAPIModels(filesystem);
+        const data = await resolveOpenAPISchemas(filesystem);
 
         return { data, specUrl };
     } catch (error) {

packages/gitbook/src/lib/openapi/types.ts

@@ -2,7 +2,7 @@ import type { DocumentBlockOpenAPI, DocumentBlockOpenAPIOperation } from '@gitbo
 import type { Filesystem, OpenAPIParseError, OpenAPIV3xDocument } from '@gitbook/openapi-parser';
 import type { GitBookAnyContext } from '@v2/lib/context';
 
-//!!TODO: Add DocumentBlockOpenAPIModels when available in @gitbook/api
+//!!TODO: Add DocumentBlockOpenAPISchemas when available in @gitbook/api
 export type AnyOpenAPIBlock = DocumentBlockOpenAPI | DocumentBlockOpenAPIOperation;
 
 /**

packages/react-openapi/src/index.ts

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

packages/react-openapi/src/models/index.ts

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

packages/react-openapi/src/schemas/OpenAPISchemas.tsx

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

packages/react-openapi/src/schemas/index.ts

@@ -0,0 +1,2 @@
+export * from './OpenAPISchemas';
+export * from './resolveOpenAPISchemas';

packages/react-openapi/src/schemas/resolveOpenAPISchemas.ts

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

packages/react-openapi/src/types.ts

@@ -56,12 +56,12 @@ export interface OpenAPIOperationData extends OpenAPICustomSpecProperties {
     securities: [string, OpenAPIV3.SecuritySchemeObject][];
 }
 
-export type OpenAPIModel = {
+export type OpenAPISchema = {
     name: string;
     schema: OpenAPIV3.SchemaObject;
 };
 
-export interface OpenAPIModelsData {
+export interface OpenAPISchemasData {
-    /** Components schemas to be used for models */
+    /** Components schemas to be used for schemas */
-    models: OpenAPIModel[];
+    schemas: OpenAPISchema[];
 }