zod-nest 2.0.1 → 2.1.0

package/dist/index.d.mts

@@ -831,6 +831,18 @@ interface ApplyZodNestOptions {
      * `@ZodQuery({ ref })` override takes precedence over this preference.
      */
     queryParamStyle?: QueryParamStyle;
+    /**
+     * Copy each named component's `title` (when set via `.meta({ title })`) onto
+     * every `$ref` that targets it, as a sibling: `{ $ref, title }` (default
+     * `true`).
+     *
+     * OpenAPI 3.1 allows siblings next to `$ref`, and Swagger UI's 3.1 renderer
+     * inlines referenced schemas without showing their component name
+     * (swagger-api/swagger-ui#9540); the sibling `title` gives the renderer (and
+     * other 3.1-aware tools) a name to display. The annotation is semantically
+     * inert. Set `false` to emit bare `$ref`s.
+     */
+    refTitles?: boolean;
 }
 /**
  * Post-processor over the OpenAPI document emitted by
@@ -856,6 +868,9 @@ interface ApplyZodNestOptions {
  *   transitive `$ref` deps, plus any `{ expose: true }` opt-ins) are kept —
  *   unreferenced registered schemas are pruned. Exposure is document-scoped, so
  *   several documents sharing one registry each carry only what they use.
+ * - Each named component's `title` is copied onto every `$ref` that targets it
+ *   as a `{ $ref, title }` sibling (`applyRefTitles`, unless `refTitles: false`)
+ *   so Swagger UI's 3.1 renderer surfaces the component name. Inert annotation.
  * - Every `$ref` whose target is missing throws `ZodNestDocumentError(DANGLING_REF)`.
  * - `doc.openapi` is set to `'3.1.0'` — zod-nest emits OpenAPI 3.1 only; this
  *   guarantees the version string matches the emitted body regardless of the

package/dist/index.d.ts

@@ -831,6 +831,18 @@ interface ApplyZodNestOptions {
      * `@ZodQuery({ ref })` override takes precedence over this preference.
      */
     queryParamStyle?: QueryParamStyle;
+    /**
+     * Copy each named component's `title` (when set via `.meta({ title })`) onto
+     * every `$ref` that targets it, as a sibling: `{ $ref, title }` (default
+     * `true`).
+     *
+     * OpenAPI 3.1 allows siblings next to `$ref`, and Swagger UI's 3.1 renderer
+     * inlines referenced schemas without showing their component name
+     * (swagger-api/swagger-ui#9540); the sibling `title` gives the renderer (and
+     * other 3.1-aware tools) a name to display. The annotation is semantically
+     * inert. Set `false` to emit bare `$ref`s.
+     */
+    refTitles?: boolean;
 }
 /**
  * Post-processor over the OpenAPI document emitted by
@@ -856,6 +868,9 @@ interface ApplyZodNestOptions {
  *   transitive `$ref` deps, plus any `{ expose: true }` opt-ins) are kept —
  *   unreferenced registered schemas are pruned. Exposure is document-scoped, so
  *   several documents sharing one registry each carry only what they use.
+ * - Each named component's `title` is copied onto every `$ref` that targets it
+ *   as a `{ $ref, title }` sibling (`applyRefTitles`, unless `refTitles: false`)
+ *   so Swagger UI's 3.1 renderer surfaces the component name. Inert annotation.
  * - Every `$ref` whose target is missing throws `ZodNestDocumentError(DANGLING_REF)`.
  * - `doc.openapi` is set to `'3.1.0'` — zod-nest emits OpenAPI 3.1 only; this
  *   guarantees the version string matches the emitted body regardless of the

package/dist/index.js

@@ -1334,7 +1334,7 @@ var ZodResponse = /* @__PURE__ */ __name((opts) => {
 }, "ZodResponse");
 
 // src/decorators/internal/zod-schema-ref.ts
-var resolveSchemaRef = /* @__PURE__ */ __name((schema, options) => {
+function resolveSchemaRef(schema, options) {
   const registry = options?.registry ?? defaultRegistry;
   const id = registerSchema(schema, registry, {
     id: options?.id
@@ -1371,7 +1371,8 @@ var resolveSchemaRef = /* @__PURE__ */ __name((schema, options) => {
     kind: "inline",
     schema: body
   };
-}, "resolveSchemaRef");
+}
+__name(resolveSchemaRef, "resolveSchemaRef");
 
 // src/decorators/internal/zod-param-expand.ts
 var isZodObject = /* @__PURE__ */ __name((schema) => schema._zod.def.type === "object", "isZodObject");
@@ -1505,12 +1506,11 @@ var resolveBodySchema = /* @__PURE__ */ __name((schema, options) => {
   if (options?.flatten === true) {
     return flattenObjectIntersection(schema, options.registry ?? defaultRegistry, "@ZodBody");
   }
-  const resolution = resolveSchemaRef(schema, {
+  return resolveSchemaRef(schema, {
     id: options?.id,
     registry: options?.registry,
     deferAnonInline: true
-  });
-  return resolution.kind === "ref" ? resolution.ref : resolution.schema;
+  }).ref;
 }, "resolveBodySchema");
 
 // src/decorators/internal/query-marker.ts
@@ -2382,6 +2382,47 @@ var decorateIfPresent = /* @__PURE__ */ __name((schemas, key) => {
   };
 }, "decorateIfPresent");
 
+// src/document/ref-titles.ts
+var applyRefTitles = /* @__PURE__ */ __name((doc) => {
+  const schemas = doc.components?.schemas;
+  if (schemas === void 0) {
+    return;
+  }
+  const titleById = /* @__PURE__ */ new Map();
+  for (const [id, body] of Object.entries(schemas)) {
+    if (isPlainRecord5(body) && typeof body.title === "string" && body.title !== "") {
+      titleById.set(id, body.title);
+    }
+  }
+  if (titleById.size === 0) {
+    return;
+  }
+  addRefTitles(doc.paths, titleById);
+  addRefTitles(schemas, titleById);
+}, "applyRefTitles");
+var isPlainRecord5 = /* @__PURE__ */ __name((value) => value !== null && typeof value === "object" && !Array.isArray(value), "isPlainRecord");
+var addRefTitles = /* @__PURE__ */ __name((node, titleById) => {
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      addRefTitles(item, titleById);
+    }
+    return;
+  }
+  if (!isPlainRecord5(node)) {
+    return;
+  }
+  const ref = node.$ref;
+  if (typeof ref === "string" && ref.startsWith(COMPONENTS_SCHEMAS_PREFIX) && node.title === void 0) {
+    const title = titleById.get(ref.slice(COMPONENTS_SCHEMAS_PREFIX.length));
+    if (title !== void 0) {
+      node.title = title;
+    }
+  }
+  for (const value of Object.values(node)) {
+    addRefTitles(value, titleById);
+  }
+}, "addRefTitles");
+
 // src/document/rewrite-refs.ts
 var rewriteRefs2 = /* @__PURE__ */ __name((params) => {
   const { doc, renames, divergentOutputIds } = params;
@@ -2527,6 +2568,9 @@ var applyZodNest = /* @__PURE__ */ __name((doc, opts = {}) => {
     doc,
     registry
   });
+  if (opts.refTitles !== false) {
+    applyRefTitles(doc);
+  }
   assertNoDanglingRefs({
     doc,
     collected: extended