From f127d286757501e7effc2d7e68882aa000b10a7a Mon Sep 17 00:00:00 2001 From: "Nolann B." <100787331+nolannbiron@users.noreply.github.com> Date: Fri, 7 Mar 2025 22:28:37 +0100 Subject: [PATCH] Rename OpenAPIModels to OpenAPISchemas (#2946) --- .changeset/healthy-paws-flash.md | 6 ++++ .../components/DocumentView/OpenAPI/style.css | 6 ++-- ...Block.ts => resolveOpenAPISchemasBlock.ts} | 20 +++++------ packages/gitbook/src/lib/openapi/types.ts | 2 +- packages/react-openapi/src/index.ts | 4 +-- packages/react-openapi/src/models/index.ts | 2 -- .../OpenAPISchemas.tsx} | 36 +++++++++---------- packages/react-openapi/src/schemas/index.ts | 2 ++ .../resolveOpenAPISchemas.ts} | 18 +++++----- packages/react-openapi/src/types.ts | 8 ++--- 10 files changed, 55 insertions(+), 49 deletions(-) create mode 100644 .changeset/healthy-paws-flash.md rename packages/gitbook/src/lib/openapi/{resolveOpenAPIModelsBlock.ts => resolveOpenAPISchemasBlock.ts} (69%) delete mode 100644 packages/react-openapi/src/models/index.ts rename packages/react-openapi/src/{models/OpenAPIModels.tsx => schemas/OpenAPISchemas.tsx} (73%) create mode 100644 packages/react-openapi/src/schemas/index.ts rename packages/react-openapi/src/{models/resolveOpenAPIModels.ts => schemas/resolveOpenAPISchemas.ts} (56%) diff --git a/.changeset/healthy-paws-flash.md b/.changeset/healthy-paws-flash.md new file mode 100644 index 000000000..a27064632 --- /dev/null +++ b/.changeset/healthy-paws-flash.md @@ -0,0 +1,6 @@ +--- +'@gitbook/react-openapi': patch +'gitbook': patch +--- + +Rename OpenAPIModels to OpenAPISchemas diff --git a/packages/gitbook/src/components/DocumentView/OpenAPI/style.css b/packages/gitbook/src/components/DocumentView/OpenAPI/style.css index c538c3de9..7cd8ad25a 100644 --- a/packages/gitbook/src/components/DocumentView/OpenAPI/style.css +++ b/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; } diff --git a/packages/gitbook/src/lib/openapi/resolveOpenAPIModelsBlock.ts b/packages/gitbook/src/lib/openapi/resolveOpenAPISchemasBlock.ts similarity index 69% rename from packages/gitbook/src/lib/openapi/resolveOpenAPIModelsBlock.ts rename to packages/gitbook/src/lib/openapi/resolveOpenAPISchemasBlock.ts index 6c89e2025..10f5ae8f8 100644 --- a/packages/gitbook/src/lib/openapi/resolveOpenAPIModelsBlock.ts +++ b/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; +type ResolveOpenAPISchemasBlockResult = ResolveOpenAPIBlockResult; -const weakmap = new WeakMap>(); +const weakmap = new WeakMap>(); /** * 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 { +): Promise { 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 { +): Promise { 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) { diff --git a/packages/gitbook/src/lib/openapi/types.ts b/packages/gitbook/src/lib/openapi/types.ts index 336c08aa9..f591d592b 100644 --- a/packages/gitbook/src/lib/openapi/types.ts +++ b/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; /** diff --git a/packages/react-openapi/src/index.ts b/packages/react-openapi/src/index.ts index 832ff0684..f2e6f90bd 100644 --- a/packages/react-openapi/src/index.ts +++ b/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'; diff --git a/packages/react-openapi/src/models/index.ts b/packages/react-openapi/src/models/index.ts deleted file mode 100644 index 88dca43d6..000000000 --- a/packages/react-openapi/src/models/index.ts +++ /dev/null @@ -1,2 +0,0 @@ -export * from './OpenAPIModels'; -export * from './resolveOpenAPIModels'; diff --git a/packages/react-openapi/src/models/OpenAPIModels.tsx b/packages/react-openapi/src/schemas/OpenAPISchemas.tsx similarity index 73% rename from packages/react-openapi/src/models/OpenAPIModels.tsx rename to packages/react-openapi/src/schemas/OpenAPISchemas.tsx index 2e9030a16..860b574f3 100644 --- a/packages/react-openapi/src/models/OpenAPIModels.tsx +++ b/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 ( -
- +
+
); } /** - * Root schema for OpenAPI models. - * It displays a single model or a disclosure group for multiple models. + * Root schema for OpenAPI schemas. + * It displays a single model or a disclosure group for multiple schemas. */ -function OpenAPIRootModelsSchema(props: { - models: OpenAPIModelsData['models']; +function OpenAPIRootSchemasSchema(props: { + 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) { - const schema = models?.[0]?.schema; + if (schemas.length === 1) { + 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 ( ({ + groups={schemas.map(({ name, schema }) => ({ id: name, label: (
@@ -75,7 +75,7 @@ function OpenAPIRootModelsSchema(props: { { id: 'model', body: ( -
+
diff --git a/packages/react-openapi/src/schemas/index.ts b/packages/react-openapi/src/schemas/index.ts new file mode 100644 index 000000000..9747866bc --- /dev/null +++ b/packages/react-openapi/src/schemas/index.ts @@ -0,0 +1,2 @@ +export * from './OpenAPISchemas'; +export * from './resolveOpenAPISchemas'; diff --git a/packages/react-openapi/src/models/resolveOpenAPIModels.ts b/packages/react-openapi/src/schemas/resolveOpenAPISchemas.ts similarity index 56% rename from packages/react-openapi/src/models/resolveOpenAPIModels.ts rename to packages/react-openapi/src/schemas/resolveOpenAPISchemas.ts index 5f9d8d878..a377a12ea 100644 --- a/packages/react-openapi/src/models/resolveOpenAPIModels.ts +++ b/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. - * Models are extracted from the OpenAPI components.schemas + * Resolve an OpenAPI schemas from a file and compile it to a more usable format. + * Schemas are extracted from the OpenAPI components.schemas */ -export async function resolveOpenAPIModels( +export async function resolveOpenAPISchemas( filesystem: Filesystem -): Promise { +): Promise { 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)) diff --git a/packages/react-openapi/src/types.ts b/packages/react-openapi/src/types.ts index fa7f5bf8c..9f7829055 100644 --- a/packages/react-openapi/src/types.ts +++ b/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 { - /** Components schemas to be used for models */ - models: OpenAPIModel[]; +export interface OpenAPISchemasData { + /** Components schemas to be used for schemas */ + schemas: OpenAPISchema[]; }