packages/core/openapi/src/utils/zod.ts - develop - githubmirror/strapi

packages/core/openapi/src/utils/zod.ts
78 строк3 KB
Nico André
chore(lint): add non-blocking oxlint setup (#26923)
31 июл 2026, 16:56
31 июл 2026, 16:566469af3
import { randomUUID } from 'node:crypto';
import * as z from 'zod/v4';

import type { OpenAPIV3_1 } from 'openapi-types';

/**
 * Zod ≥3.25.76 embeds `$id` in `toJSONSchema` output (set after `override`).
 * Strip it so OpenAPI documents stay stable — inline schemas use random UUIDs
 * as registry ids — and match the pre-3.25.76 shape.
 */
export const stripJsonSchemaId = <T extends object>(schema: T): T => {
  if ('$id' in schema) {
    delete (schema as { $id?: string }).$id;
  }
  return schema;
};

/**
 * Converts a Zod schema to an OpenAPI Schema Object.
 *
 * @description
 * Takes a Zod schema and converts it into an OpenAPI Schema Object (v3.1).
 * It uses a local registry to handle the conversion process and generates the appropriate
 * OpenAPI components.
 *
 * @param zodSchema - The Zod schema to convert to OpenAPI format. Can be any valid Zod schema.
 *
 * @returns An OpenAPI Schema Object representing the input Zod schema structure.
 * If the conversion cannot be completed, returns undefined.
 *
 * @example
 * ```typescript
 * import * as z from 'zod/v4';
 *
 * // Create a Zod schema
 * const userSchema = z.object({
 *   id: z.number(),
 *   name: z.string(),
 *   email: z.string().email()
 * });
 *
 * // Convert to OpenAPI schema
 * const openAPISchema = zodToOpenAPI(userSchema);
 * ```
 */
export const zodToOpenAPI = (
  zodSchema: z.ZodType
): OpenAPIV3_1.SchemaObject | OpenAPIV3_1.ReferenceObject => {
  try {
    const id = randomUUID();
    const registry = z.registry<{ id: string }>();

    // Add the schema to the local registry with a custom, unique ID
    registry.add(zodSchema, { id });

    // Copy the global registry definitions into the local registry to make sure references are resolved
    // This prevent "__shared" definitions from being created
    for (const [key, value] of z.globalRegistry._idmap) {
      registry.add(value, { id: key });
    }

    // Generate the schemas and only return the one we want, transform the URI path to be OpenAPI compliant
    const { schemas } = z.toJSONSchema(registry, { uri: toComponentsPath });

    // TODO: make sure it's compliant
    return stripJsonSchemaId(schemas[id] as OpenAPIV3_1.SchemaObject);
  } catch {
    throw new Error("Couldn't transform the zod schema into an OpenAPI schema");
  }
};

/**
 * Generates a path string for referencing a component schema by its identifier.
 *
 * @param id - The identifier of the component schema.
 * @returns The constructed path string for the specified component schema.
 */
export const toComponentsPath = (id: string) => `#/components/schemas/${id}`;