next-openapi-gen 1.2.3 → 1.3.0

package/README.md

@@ -288,33 +288,34 @@ Version guidance:
 | `ignoreRoutes`                        | Exclude routes with wildcard support                             |
 | `defaultResponseSet` / `responseSets` | Reusable error-response groups                                   |
 | `errorConfig`                         | Shared error schema templates                                    |
+| `authPresets`                         | Override or extend the `@auth` keyword → scheme-name mapping     |
 
 For a fuller setup guide, Pages Router notes, response sets, and route exclusion
 patterns, see [docs/getting-started.md](./docs/getting-started.md).
 
 ## JSDoc tags you will use most
 
-| Tag                        | Purpose                                                          |
-| -------------------------- | ---------------------------------------------------------------- |
-| `@pathParams`              | Path parameter schema or type                                    |
-| `@params` / `@queryParams` | Query parameter schema or type                                   |
-| `@header` / `@cookie`      | Header / cookie parameter schema or type                         |
-| `@body`                    | Request body schema or type                                      |
-| `@response`                | Response schema, code, and optional description                  |
-| `@responseDescription`     | Response description without redefining the schema               |
-| `@responseHeader`          | Add a response header to a given status code                     |
-| `@link`                    | Add an OpenAPI link to a response                                |
-| `@auth` / `@security`      | Security requirement(s); `@security` accepts explicit scopes     |
-| `@servers`                 | Operation-level servers                                          |
-| `@externalDocs`            | Operation-level external documentation                           |
-| `@callback`                | OpenAPI operation callback                                       |
-| `@webhook`                 | Mark the handler as a webhook (`3.1`+ `webhooks` section)        |
-| `@contentType`             | Request content type such as `multipart/form-data`               |
-| `@examples`                | Request, response, and querystring examples                      |
-| `@openapi`                 | Explicit inclusion marker when `includeOpenApiRoutes` is enabled |
-| `@openapi-override`        | Deep-merge extra OpenAPI fields onto the operation               |
-| `@ignore`                  | Exclude a route from generation                                  |
-| `@method`                  | Required HTTP method tag for Pages Router handlers               |
+| Tag                        | Purpose                                                                                                 |
+| -------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `@pathParams`              | Path parameter schema or type                                                                           |
+| `@params` / `@queryParams` | Query parameter schema or type                                                                          |
+| `@header` / `@cookie`      | Header / cookie parameter schema or type                                                                |
+| `@body`                    | Request body schema or type                                                                             |
+| `@response`                | Response schema, code, and optional description                                                         |
+| `@responseDescription`     | Response description without redefining the schema                                                      |
+| `@responseHeader`          | Add a response header to a given status code                                                            |
+| `@link`                    | Add an OpenAPI link to a response                                                                       |
+| `@auth` / `@security`      | Security requirement(s); built-in presets: `bearer`, `basic`, `apikey` — configurable via `authPresets` |
+| `@servers`                 | Operation-level servers                                                                                 |
+| `@externalDocs`            | Operation-level external documentation                                                                  |
+| `@callback`                | OpenAPI operation callback                                                                              |
+| `@webhook`                 | Mark the handler as a webhook (`3.1`+ `webhooks` section)                                               |
+| `@contentType`             | Request content type such as `multipart/form-data`                                                      |
+| `@examples`                | Request, response, and querystring examples                                                             |
+| `@openapi`                 | Explicit inclusion marker when `includeOpenApiRoutes` is enabled                                        |
+| `@openapi-override`        | Deep-merge extra OpenAPI fields onto the operation                                                      |
+| `@ignore`                  | Exclude a route from generation                                                                         |
+| `@method`                  | Required HTTP method tag for Pages Router handlers                                                      |
 
 For the complete tag guide and usage recipes, see
 [docs/jsdoc-reference.md](./docs/jsdoc-reference.md).

package/dist/cli.js

@@ -667,6 +667,7 @@ function normalizeOpenApiConfig(template) {
     outputDir: template.outputDir ?? DEFAULT_OUTPUT_DIR,
     includeOpenApiRoutes: template.includeOpenApiRoutes ?? DEFAULT_INCLUDE_OPENAPI_ROUTES,
     ignoreRoutes: template.ignoreRoutes ?? [],
+    excludeSchemas: template.excludeSchemas ?? [],
     schemaType: template.schemaType ?? DEFAULT_RUNTIME_SCHEMA_TYPE,
     schemaBackends,
     schemaFiles: template.schemaFiles ?? [],
@@ -1406,6 +1407,17 @@ function mergeJSDocData(target, source) {
 function cleanComment(commentValue) {
   return commentValue.replace(/\*\s*/g, "").trim();
 }
+function extractInternalFlagFromComments(comments) {
+  if (!comments)
+    return false;
+  for (const comment of comments) {
+    const cleaned = cleanComment(comment.value);
+    if (/@internal\b/.test(cleaned) || /@schema\s+false\b/.test(cleaned)) {
+      return true;
+    }
+  }
+  return false;
+}
 function extractSchemaIdFromComments(comments) {
   if (!comments)
     return null;
@@ -1702,7 +1714,8 @@ var INTERNAL_OPENAPI_CONFIG_KEYS = [
   "framework",
   "next",
   "diagnostics",
-  "debug"
+  "debug",
+  "excludeSchemas"
 ];
 var AUTH_PRESET_REPLACEMENTS = {
   bearer: "BearerAuth",
@@ -12145,6 +12158,8 @@ var ZodSchemaConverter = class {
   /** Schema variable names whose component name was overridden via .meta({ id }). These must
    *  NOT be copied back under the original variable name in the OpenAPI components object. */
   metaIdSchemaNames = /* @__PURE__ */ new Set();
+  /** Schema variable names marked @internal — excluded from components/schemas output. */
+  internalSchemaNames = /* @__PURE__ */ new Set();
   // Current processing context (set during file processing)
   currentFilePath;
   currentAST;
@@ -13766,7 +13781,13 @@ var ZodSchemaConverter = class {
    * Get all processed Zod schemas
    */
   getProcessedSchemas() {
-    return this.zodSchemas;
+    const result = {};
+    for (const [name, schema] of Object.entries(this.zodSchemas)) {
+      if (!this.internalSchemaNames.has(name)) {
+        result[name] = schema;
+      }
+    }
+    return result;
   }
   /**
    * Pre-scan all files to build type mappings
@@ -13818,6 +13839,15 @@ var ZodSchemaConverter = class {
               if (t10.isIdentifier(declaration.id) && declaration.init) {
                 const schemaName = declaration.id.name;
                 if (this.isZodSchema(declaration.init)) {
+                  const decl = path25.node.declaration;
+                  const allComments = [
+                    ...path25.node.leadingComments ?? [],
+                    ...decl?.leadingComments ?? [],
+                    ...declaration.leadingComments ?? []
+                  ];
+                  if (extractInternalFlagFromComments(allComments)) {
+                    this.internalSchemaNames.add(schemaName);
+                  }
                   if (!this.getStoredSchema(schemaName)) {
                     logger.debug(`Pre-processing Zod schema: ${schemaName}`);
                     this.processingSchemas.add(schemaName);
@@ -13843,6 +13873,13 @@ var ZodSchemaConverter = class {
             if (t10.isIdentifier(declaration.id) && declaration.init) {
               const schemaName = declaration.id.name;
               if (this.isZodSchema(declaration.init)) {
+                const allComments = [
+                  ...path25.node.leadingComments ?? [],
+                  ...declaration.leadingComments ?? []
+                ];
+                if (extractInternalFlagFromComments(allComments)) {
+                  this.internalSchemaNames.add(schemaName);
+                }
                 if (!this.getStoredSchema(schemaName) && !this.processingSchemas.has(schemaName)) {
                   logger.debug(`Pre-processing Zod schema: ${schemaName}`);
                   this.processingSchemas.add(schemaName);
@@ -14577,7 +14614,7 @@ function collectFirstMemberLeadingComments(interfaceDecl) {
   const firstMember = body.body?.[0];
   return firstMember?.leadingComments ?? [];
 }
-function collectAllExportedDefinitions(ast, typeDefinitions, currentFile, schemaIdAliases) {
+function collectAllExportedDefinitions(ast, typeDefinitions, currentFile, schemaIdAliases, internalSchemaNames) {
   function registerDefinition(name, entry, allComments) {
     if (!typeDefinitions[name]) {
       typeDefinitions[name] = entry;
@@ -14589,6 +14626,9 @@ function collectAllExportedDefinitions(ast, typeDefinitions, currentFile, schema
         typeDefinitions[overrideId] = entry;
       }
     }
+    if (internalSchemaNames && extractInternalFlagFromComments(allComments)) {
+      internalSchemaNames.add(name);
+    }
   }
   resolvedTraverse(ast, {
     TSTypeAliasDeclaration: (path25) => {
@@ -15068,6 +15108,7 @@ var SchemaProcessor = class {
   schemaTypes;
   isResolvingPickOmitBase = false;
   schemaIdAliases = {};
+  internalSchemaNames = /* @__PURE__ */ new Set();
   fileAccess;
   symbolResolver;
   // Track imports per file for resolving ReturnType<typeof func>
@@ -15108,7 +15149,7 @@ var SchemaProcessor = class {
   getDefinedSchemas() {
     const filteredSchemas = {};
     Object.entries(this.openapiDefinitions).forEach(([key, value]) => {
-      if (!this.schemaIdAliases[key] && !this.isGenericTypeParameter(key) && !this.isInvalidSchemaName(key) && !this.isBuiltInUtilityType(key) && !this.isFunctionSchema(key)) {
+      if (!this.schemaIdAliases[key] && !this.isGenericTypeParameter(key) && !this.isInvalidSchemaName(key) && !this.isBuiltInUtilityType(key) && !this.isFunctionSchema(key) && !this.internalSchemaNames.has(key)) {
         filteredSchemas[key] = value;
       }
     });
@@ -15118,6 +15159,22 @@ var SchemaProcessor = class {
       this.customSchemaProcessor.getDefinedSchemas()
     ]);
   }
+  getInternalSchemas() {
+    const result = {};
+    for (const name of this.internalSchemaNames) {
+      const def = this.openapiDefinitions[name];
+      if (def)
+        result[name] = def;
+    }
+    if (this.zodSchemaConverter) {
+      for (const name of this.zodSchemaConverter.internalSchemaNames) {
+        const schema = this.zodSchemaConverter.zodSchemas[name];
+        if (schema)
+          result[name] = schema;
+      }
+    }
+    return result;
+  }
   findSchemaDefinition(schemaName, contentType) {
     this.contentType = contentType;
     if (schemaName.includes("<") && schemaName.includes(">")) {
@@ -15268,7 +15325,7 @@ var SchemaProcessor = class {
    * Used when processing imported files to ensure all referenced types are available
    */
   collectAllExportedDefinitions(ast, filePath) {
-    collectAllExportedDefinitions(ast, this.typeDefinitions, filePath || this.currentFilePath, this.schemaIdAliases);
+    collectAllExportedDefinitions(ast, this.typeDefinitions, filePath || this.currentFilePath, this.schemaIdAliases, this.internalSchemaNames);
   }
   collectTypeDefinitions(ast, schemaName, filePath) {
     collectTypeDefinitions(ast, schemaName, this.typeDefinitions, filePath || this.currentFilePath);
@@ -17254,6 +17311,64 @@ function generateErrorResponsesFromConfig(document, errorConfig) {
   });
 }
 
+// ../openapi-core/dist/core/exclude-schemas.js
+function patternToRegExp(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${escaped.replace(/\*/g, ".*")}$`);
+}
+function matchExcludePatterns(names, patterns) {
+  if (patterns.length === 0)
+    return [];
+  const regexes = patterns.map(patternToRegExp);
+  return names.filter((name) => regexes.some((re) => re.test(name)));
+}
+function applyExcludeSchemas(document, mergedSchemas, excludedSchemas) {
+  const excludedNames = new Set(Object.keys(excludedSchemas));
+  if (excludedNames.size === 0)
+    return;
+  walkAndInline(document, excludedSchemas, excludedNames, /* @__PURE__ */ new Set());
+  for (const name of excludedNames) {
+    delete mergedSchemas[name];
+  }
+}
+function walkAndInline(obj, excluded, excludedNames, visiting) {
+  if (!obj || typeof obj !== "object")
+    return;
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      walkAndInline(item, excluded, excludedNames, visiting);
+    }
+    return;
+  }
+  const rec = obj;
+  const ref = rec["$ref"];
+  if (typeof ref === "string") {
+    const match = ref.match(/^#\/components\/schemas\/(.+)$/);
+    const name = match?.[1];
+    if (name && excludedNames.has(name)) {
+      if (visiting.has(name)) {
+        logger.warn(`Circular reference to internal schema "${name}", keeping $ref`);
+        return;
+      }
+      const schemaDef = excluded[name];
+      if (schemaDef) {
+        const cloned = JSON.parse(JSON.stringify(schemaDef));
+        delete rec["$ref"];
+        Object.assign(rec, cloned);
+        const newVisiting = new Set(visiting);
+        newVisiting.add(name);
+        for (const key of Object.keys(rec)) {
+          walkAndInline(rec[key], excluded, excludedNames, newVisiting);
+        }
+        return;
+      }
+    }
+  }
+  for (const key of Object.keys(rec)) {
+    walkAndInline(rec[key], excluded, excludedNames, visiting);
+  }
+}
+
 // ../openapi-core/dist/core/orchestrator.js
 function runGenerationOrchestrator({ config: config2, template, hooks, runtime, createFrameworkSource }) {
   const diagnostics = new DiagnosticsCollector();
@@ -17324,11 +17439,21 @@ function runGenerationOrchestrator({ config: config2, template, hooks, runtime,
   }
   profile.defaultComponentsAndErrorsMs = performance.now() - phaseStartedAt;
   phaseStartedAt = performance.now();
-  const definedSchemas = routeProcessor.getSchemaProcessor().getDefinedSchemas();
+  const schemaProcessor = routeProcessor.getSchemaProcessor();
+  const definedSchemas = schemaProcessor.getDefinedSchemas();
   const mergedSchemas = {
     ...document.components.schemas,
     ...definedSchemas
   };
+  const internalSchemas = schemaProcessor.getInternalSchemas();
+  const patternExcludedNames = matchExcludePatterns(Object.keys(mergedSchemas), config2.excludeSchemas ?? []);
+  const allExcludedSchemas = {
+    ...internalSchemas,
+    ...Object.fromEntries(patternExcludedNames.map((name) => [name, mergedSchemas[name]]))
+  };
+  if (Object.keys(allExcludedSchemas).length > 0) {
+    applyExcludeSchemas(document, mergedSchemas, allExcludedSchemas);
+  }
   if (Object.keys(mergedSchemas).length > 0) {
     document.components.schemas = Object.fromEntries(Object.entries(mergedSchemas).sort(([a], [b]) => a.localeCompare(b, "en", { sensitivity: "base" })));
   }

package/dist/index.js

@@ -211,6 +211,7 @@ function normalizeOpenApiConfig(template) {
     outputDir: template.outputDir ?? DEFAULT_OUTPUT_DIR,
     includeOpenApiRoutes: template.includeOpenApiRoutes ?? DEFAULT_INCLUDE_OPENAPI_ROUTES,
     ignoreRoutes: template.ignoreRoutes ?? [],
+    excludeSchemas: template.excludeSchemas ?? [],
     schemaType: template.schemaType ?? DEFAULT_RUNTIME_SCHEMA_TYPE,
     schemaBackends,
     schemaFiles: template.schemaFiles ?? [],
@@ -950,6 +951,17 @@ function mergeJSDocData(target, source) {
 function cleanComment(commentValue) {
   return commentValue.replace(/\*\s*/g, "").trim();
 }
+function extractInternalFlagFromComments(comments) {
+  if (!comments)
+    return false;
+  for (const comment of comments) {
+    const cleaned = cleanComment(comment.value);
+    if (/@internal\b/.test(cleaned) || /@schema\s+false\b/.test(cleaned)) {
+      return true;
+    }
+  }
+  return false;
+}
 function extractSchemaIdFromComments(comments) {
   if (!comments)
     return null;
@@ -1246,7 +1258,8 @@ var INTERNAL_OPENAPI_CONFIG_KEYS = [
   "framework",
   "next",
   "diagnostics",
-  "debug"
+  "debug",
+  "excludeSchemas"
 ];
 var AUTH_PRESET_REPLACEMENTS = {
   bearer: "BearerAuth",
@@ -11694,6 +11707,8 @@ var ZodSchemaConverter = class {
   /** Schema variable names whose component name was overridden via .meta({ id }). These must
    *  NOT be copied back under the original variable name in the OpenAPI components object. */
   metaIdSchemaNames = /* @__PURE__ */ new Set();
+  /** Schema variable names marked @internal — excluded from components/schemas output. */
+  internalSchemaNames = /* @__PURE__ */ new Set();
   // Current processing context (set during file processing)
   currentFilePath;
   currentAST;
@@ -13315,7 +13330,13 @@ var ZodSchemaConverter = class {
    * Get all processed Zod schemas
    */
   getProcessedSchemas() {
-    return this.zodSchemas;
+    const result = {};
+    for (const [name, schema] of Object.entries(this.zodSchemas)) {
+      if (!this.internalSchemaNames.has(name)) {
+        result[name] = schema;
+      }
+    }
+    return result;
   }
   /**
    * Pre-scan all files to build type mappings
@@ -13367,6 +13388,15 @@ var ZodSchemaConverter = class {
               if (t10.isIdentifier(declaration.id) && declaration.init) {
                 const schemaName = declaration.id.name;
                 if (this.isZodSchema(declaration.init)) {
+                  const decl = path25.node.declaration;
+                  const allComments = [
+                    ...path25.node.leadingComments ?? [],
+                    ...decl?.leadingComments ?? [],
+                    ...declaration.leadingComments ?? []
+                  ];
+                  if (extractInternalFlagFromComments(allComments)) {
+                    this.internalSchemaNames.add(schemaName);
+                  }
                   if (!this.getStoredSchema(schemaName)) {
                     logger.debug(`Pre-processing Zod schema: ${schemaName}`);
                     this.processingSchemas.add(schemaName);
@@ -13392,6 +13422,13 @@ var ZodSchemaConverter = class {
             if (t10.isIdentifier(declaration.id) && declaration.init) {
               const schemaName = declaration.id.name;
               if (this.isZodSchema(declaration.init)) {
+                const allComments = [
+                  ...path25.node.leadingComments ?? [],
+                  ...declaration.leadingComments ?? []
+                ];
+                if (extractInternalFlagFromComments(allComments)) {
+                  this.internalSchemaNames.add(schemaName);
+                }
                 if (!this.getStoredSchema(schemaName) && !this.processingSchemas.has(schemaName)) {
                   logger.debug(`Pre-processing Zod schema: ${schemaName}`);
                   this.processingSchemas.add(schemaName);
@@ -14126,7 +14163,7 @@ function collectFirstMemberLeadingComments(interfaceDecl) {
   const firstMember = body.body?.[0];
   return firstMember?.leadingComments ?? [];
 }
-function collectAllExportedDefinitions(ast, typeDefinitions, currentFile, schemaIdAliases) {
+function collectAllExportedDefinitions(ast, typeDefinitions, currentFile, schemaIdAliases, internalSchemaNames) {
   function registerDefinition(name, entry, allComments) {
     if (!typeDefinitions[name]) {
       typeDefinitions[name] = entry;
@@ -14138,6 +14175,9 @@ function collectAllExportedDefinitions(ast, typeDefinitions, currentFile, schema
         typeDefinitions[overrideId] = entry;
       }
     }
+    if (internalSchemaNames && extractInternalFlagFromComments(allComments)) {
+      internalSchemaNames.add(name);
+    }
   }
   resolvedTraverse(ast, {
     TSTypeAliasDeclaration: (path25) => {
@@ -14617,6 +14657,7 @@ var SchemaProcessor = class {
   schemaTypes;
   isResolvingPickOmitBase = false;
   schemaIdAliases = {};
+  internalSchemaNames = /* @__PURE__ */ new Set();
   fileAccess;
   symbolResolver;
   // Track imports per file for resolving ReturnType<typeof func>
@@ -14657,7 +14698,7 @@ var SchemaProcessor = class {
   getDefinedSchemas() {
     const filteredSchemas = {};
     Object.entries(this.openapiDefinitions).forEach(([key, value]) => {
-      if (!this.schemaIdAliases[key] && !this.isGenericTypeParameter(key) && !this.isInvalidSchemaName(key) && !this.isBuiltInUtilityType(key) && !this.isFunctionSchema(key)) {
+      if (!this.schemaIdAliases[key] && !this.isGenericTypeParameter(key) && !this.isInvalidSchemaName(key) && !this.isBuiltInUtilityType(key) && !this.isFunctionSchema(key) && !this.internalSchemaNames.has(key)) {
         filteredSchemas[key] = value;
       }
     });
@@ -14667,6 +14708,22 @@ var SchemaProcessor = class {
       this.customSchemaProcessor.getDefinedSchemas()
     ]);
   }
+  getInternalSchemas() {
+    const result = {};
+    for (const name of this.internalSchemaNames) {
+      const def = this.openapiDefinitions[name];
+      if (def)
+        result[name] = def;
+    }
+    if (this.zodSchemaConverter) {
+      for (const name of this.zodSchemaConverter.internalSchemaNames) {
+        const schema = this.zodSchemaConverter.zodSchemas[name];
+        if (schema)
+          result[name] = schema;
+      }
+    }
+    return result;
+  }
   findSchemaDefinition(schemaName, contentType) {
     this.contentType = contentType;
     if (schemaName.includes("<") && schemaName.includes(">")) {
@@ -14817,7 +14874,7 @@ var SchemaProcessor = class {
    * Used when processing imported files to ensure all referenced types are available
    */
   collectAllExportedDefinitions(ast, filePath) {
-    collectAllExportedDefinitions(ast, this.typeDefinitions, filePath || this.currentFilePath, this.schemaIdAliases);
+    collectAllExportedDefinitions(ast, this.typeDefinitions, filePath || this.currentFilePath, this.schemaIdAliases, this.internalSchemaNames);
   }
   collectTypeDefinitions(ast, schemaName, filePath) {
     collectTypeDefinitions(ast, schemaName, this.typeDefinitions, filePath || this.currentFilePath);
@@ -16803,6 +16860,64 @@ function generateErrorResponsesFromConfig(document, errorConfig) {
   });
 }
 
+// ../openapi-core/dist/core/exclude-schemas.js
+function patternToRegExp(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${escaped.replace(/\*/g, ".*")}$`);
+}
+function matchExcludePatterns(names, patterns) {
+  if (patterns.length === 0)
+    return [];
+  const regexes = patterns.map(patternToRegExp);
+  return names.filter((name) => regexes.some((re) => re.test(name)));
+}
+function applyExcludeSchemas(document, mergedSchemas, excludedSchemas) {
+  const excludedNames = new Set(Object.keys(excludedSchemas));
+  if (excludedNames.size === 0)
+    return;
+  walkAndInline(document, excludedSchemas, excludedNames, /* @__PURE__ */ new Set());
+  for (const name of excludedNames) {
+    delete mergedSchemas[name];
+  }
+}
+function walkAndInline(obj, excluded, excludedNames, visiting) {
+  if (!obj || typeof obj !== "object")
+    return;
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      walkAndInline(item, excluded, excludedNames, visiting);
+    }
+    return;
+  }
+  const rec = obj;
+  const ref = rec["$ref"];
+  if (typeof ref === "string") {
+    const match = ref.match(/^#\/components\/schemas\/(.+)$/);
+    const name = match?.[1];
+    if (name && excludedNames.has(name)) {
+      if (visiting.has(name)) {
+        logger.warn(`Circular reference to internal schema "${name}", keeping $ref`);
+        return;
+      }
+      const schemaDef = excluded[name];
+      if (schemaDef) {
+        const cloned = JSON.parse(JSON.stringify(schemaDef));
+        delete rec["$ref"];
+        Object.assign(rec, cloned);
+        const newVisiting = new Set(visiting);
+        newVisiting.add(name);
+        for (const key of Object.keys(rec)) {
+          walkAndInline(rec[key], excluded, excludedNames, newVisiting);
+        }
+        return;
+      }
+    }
+  }
+  for (const key of Object.keys(rec)) {
+    walkAndInline(rec[key], excluded, excludedNames, visiting);
+  }
+}
+
 // ../openapi-core/dist/core/orchestrator.js
 function runGenerationOrchestrator({ config: config2, template, hooks, runtime, createFrameworkSource }) {
   const diagnostics = new DiagnosticsCollector();
@@ -16873,11 +16988,21 @@ function runGenerationOrchestrator({ config: config2, template, hooks, runtime,
   }
   profile.defaultComponentsAndErrorsMs = performance.now() - phaseStartedAt;
   phaseStartedAt = performance.now();
-  const definedSchemas = routeProcessor.getSchemaProcessor().getDefinedSchemas();
+  const schemaProcessor = routeProcessor.getSchemaProcessor();
+  const definedSchemas = schemaProcessor.getDefinedSchemas();
   const mergedSchemas = {
     ...document.components.schemas,
     ...definedSchemas
   };
+  const internalSchemas = schemaProcessor.getInternalSchemas();
+  const patternExcludedNames = matchExcludePatterns(Object.keys(mergedSchemas), config2.excludeSchemas ?? []);
+  const allExcludedSchemas = {
+    ...internalSchemas,
+    ...Object.fromEntries(patternExcludedNames.map((name) => [name, mergedSchemas[name]]))
+  };
+  if (Object.keys(allExcludedSchemas).length > 0) {
+    applyExcludeSchemas(document, mergedSchemas, allExcludedSchemas);
+  }
   if (Object.keys(mergedSchemas).length > 0) {
     document.components.schemas = Object.fromEntries(Object.entries(mergedSchemas).sort(([a], [b]) => a.localeCompare(b, "en", { sensitivity: "base" })));
   }

package/dist/next/index.js

@@ -1306,6 +1306,17 @@ function mergeJSDocData(target, source) {
 function cleanComment(commentValue) {
   return commentValue.replace(/\*\s*/g, "").trim();
 }
+function extractInternalFlagFromComments(comments) {
+  if (!comments)
+    return false;
+  for (const comment of comments) {
+    const cleaned = cleanComment(comment.value);
+    if (/@internal\b/.test(cleaned) || /@schema\s+false\b/.test(cleaned)) {
+      return true;
+    }
+  }
+  return false;
+}
 function extractSchemaIdFromComments(comments) {
   if (!comments)
     return null;
@@ -1602,7 +1613,8 @@ var INTERNAL_OPENAPI_CONFIG_KEYS = [
   "framework",
   "next",
   "diagnostics",
-  "debug"
+  "debug",
+  "excludeSchemas"
 ];
 var AUTH_PRESET_REPLACEMENTS = {
   bearer: "BearerAuth",
@@ -2316,6 +2328,7 @@ function normalizeOpenApiConfig(template) {
     outputDir: template.outputDir ?? DEFAULT_OUTPUT_DIR,
     includeOpenApiRoutes: template.includeOpenApiRoutes ?? DEFAULT_INCLUDE_OPENAPI_ROUTES,
     ignoreRoutes: template.ignoreRoutes ?? [],
+    excludeSchemas: template.excludeSchemas ?? [],
     schemaType: template.schemaType ?? DEFAULT_RUNTIME_SCHEMA_TYPE,
     schemaBackends,
     schemaFiles: template.schemaFiles ?? [],
@@ -12728,6 +12741,8 @@ var ZodSchemaConverter = class {
   /** Schema variable names whose component name was overridden via .meta({ id }). These must
    *  NOT be copied back under the original variable name in the OpenAPI components object. */
   metaIdSchemaNames = /* @__PURE__ */ new Set();
+  /** Schema variable names marked @internal — excluded from components/schemas output. */
+  internalSchemaNames = /* @__PURE__ */ new Set();
   // Current processing context (set during file processing)
   currentFilePath;
   currentAST;
@@ -14349,7 +14364,13 @@ var ZodSchemaConverter = class {
    * Get all processed Zod schemas
    */
   getProcessedSchemas() {
-    return this.zodSchemas;
+    const result = {};
+    for (const [name, schema] of Object.entries(this.zodSchemas)) {
+      if (!this.internalSchemaNames.has(name)) {
+        result[name] = schema;
+      }
+    }
+    return result;
   }
   /**
    * Pre-scan all files to build type mappings
@@ -14401,6 +14422,15 @@ var ZodSchemaConverter = class {
               if (t11.isIdentifier(declaration.id) && declaration.init) {
                 const schemaName = declaration.id.name;
                 if (this.isZodSchema(declaration.init)) {
+                  const decl = path19.node.declaration;
+                  const allComments = [
+                    ...path19.node.leadingComments ?? [],
+                    ...decl?.leadingComments ?? [],
+                    ...declaration.leadingComments ?? []
+                  ];
+                  if (extractInternalFlagFromComments(allComments)) {
+                    this.internalSchemaNames.add(schemaName);
+                  }
                   if (!this.getStoredSchema(schemaName)) {
                     logger.debug(`Pre-processing Zod schema: ${schemaName}`);
                     this.processingSchemas.add(schemaName);
@@ -14426,6 +14456,13 @@ var ZodSchemaConverter = class {
             if (t11.isIdentifier(declaration.id) && declaration.init) {
               const schemaName = declaration.id.name;
               if (this.isZodSchema(declaration.init)) {
+                const allComments = [
+                  ...path19.node.leadingComments ?? [],
+                  ...declaration.leadingComments ?? []
+                ];
+                if (extractInternalFlagFromComments(allComments)) {
+                  this.internalSchemaNames.add(schemaName);
+                }
                 if (!this.getStoredSchema(schemaName) && !this.processingSchemas.has(schemaName)) {
                   logger.debug(`Pre-processing Zod schema: ${schemaName}`);
                   this.processingSchemas.add(schemaName);
@@ -15160,7 +15197,7 @@ function collectFirstMemberLeadingComments(interfaceDecl) {
   const firstMember = body.body?.[0];
   return firstMember?.leadingComments ?? [];
 }
-function collectAllExportedDefinitions(ast, typeDefinitions, currentFile, schemaIdAliases) {
+function collectAllExportedDefinitions(ast, typeDefinitions, currentFile, schemaIdAliases, internalSchemaNames) {
   function registerDefinition(name, entry, allComments) {
     if (!typeDefinitions[name]) {
       typeDefinitions[name] = entry;
@@ -15172,6 +15209,9 @@ function collectAllExportedDefinitions(ast, typeDefinitions, currentFile, schema
         typeDefinitions[overrideId] = entry;
       }
     }
+    if (internalSchemaNames && extractInternalFlagFromComments(allComments)) {
+      internalSchemaNames.add(name);
+    }
   }
   resolvedTraverse(ast, {
     TSTypeAliasDeclaration: (path19) => {
@@ -15651,6 +15691,7 @@ var SchemaProcessor = class {
   schemaTypes;
   isResolvingPickOmitBase = false;
   schemaIdAliases = {};
+  internalSchemaNames = /* @__PURE__ */ new Set();
   fileAccess;
   symbolResolver;
   // Track imports per file for resolving ReturnType<typeof func>
@@ -15691,7 +15732,7 @@ var SchemaProcessor = class {
   getDefinedSchemas() {
     const filteredSchemas = {};
     Object.entries(this.openapiDefinitions).forEach(([key, value]) => {
-      if (!this.schemaIdAliases[key] && !this.isGenericTypeParameter(key) && !this.isInvalidSchemaName(key) && !this.isBuiltInUtilityType(key) && !this.isFunctionSchema(key)) {
+      if (!this.schemaIdAliases[key] && !this.isGenericTypeParameter(key) && !this.isInvalidSchemaName(key) && !this.isBuiltInUtilityType(key) && !this.isFunctionSchema(key) && !this.internalSchemaNames.has(key)) {
         filteredSchemas[key] = value;
       }
     });
@@ -15701,6 +15742,22 @@ var SchemaProcessor = class {
       this.customSchemaProcessor.getDefinedSchemas()
     ]);
   }
+  getInternalSchemas() {
+    const result = {};
+    for (const name of this.internalSchemaNames) {
+      const def = this.openapiDefinitions[name];
+      if (def)
+        result[name] = def;
+    }
+    if (this.zodSchemaConverter) {
+      for (const name of this.zodSchemaConverter.internalSchemaNames) {
+        const schema = this.zodSchemaConverter.zodSchemas[name];
+        if (schema)
+          result[name] = schema;
+      }
+    }
+    return result;
+  }
   findSchemaDefinition(schemaName, contentType) {
     this.contentType = contentType;
     if (schemaName.includes("<") && schemaName.includes(">")) {
@@ -15851,7 +15908,7 @@ var SchemaProcessor = class {
    * Used when processing imported files to ensure all referenced types are available
    */
   collectAllExportedDefinitions(ast, filePath) {
-    collectAllExportedDefinitions(ast, this.typeDefinitions, filePath || this.currentFilePath, this.schemaIdAliases);
+    collectAllExportedDefinitions(ast, this.typeDefinitions, filePath || this.currentFilePath, this.schemaIdAliases, this.internalSchemaNames);
   }
   collectTypeDefinitions(ast, schemaName, filePath) {
     collectTypeDefinitions(ast, schemaName, this.typeDefinitions, filePath || this.currentFilePath);
@@ -17837,6 +17894,64 @@ function generateErrorResponsesFromConfig(document, errorConfig) {
   });
 }
 
+// ../openapi-core/dist/core/exclude-schemas.js
+function patternToRegExp(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${escaped.replace(/\*/g, ".*")}$`);
+}
+function matchExcludePatterns(names, patterns) {
+  if (patterns.length === 0)
+    return [];
+  const regexes = patterns.map(patternToRegExp);
+  return names.filter((name) => regexes.some((re) => re.test(name)));
+}
+function applyExcludeSchemas(document, mergedSchemas, excludedSchemas) {
+  const excludedNames = new Set(Object.keys(excludedSchemas));
+  if (excludedNames.size === 0)
+    return;
+  walkAndInline(document, excludedSchemas, excludedNames, /* @__PURE__ */ new Set());
+  for (const name of excludedNames) {
+    delete mergedSchemas[name];
+  }
+}
+function walkAndInline(obj, excluded, excludedNames, visiting) {
+  if (!obj || typeof obj !== "object")
+    return;
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      walkAndInline(item, excluded, excludedNames, visiting);
+    }
+    return;
+  }
+  const rec = obj;
+  const ref = rec["$ref"];
+  if (typeof ref === "string") {
+    const match = ref.match(/^#\/components\/schemas\/(.+)$/);
+    const name = match?.[1];
+    if (name && excludedNames.has(name)) {
+      if (visiting.has(name)) {
+        logger.warn(`Circular reference to internal schema "${name}", keeping $ref`);
+        return;
+      }
+      const schemaDef = excluded[name];
+      if (schemaDef) {
+        const cloned = JSON.parse(JSON.stringify(schemaDef));
+        delete rec["$ref"];
+        Object.assign(rec, cloned);
+        const newVisiting = new Set(visiting);
+        newVisiting.add(name);
+        for (const key of Object.keys(rec)) {
+          walkAndInline(rec[key], excluded, excludedNames, newVisiting);
+        }
+        return;
+      }
+    }
+  }
+  for (const key of Object.keys(rec)) {
+    walkAndInline(rec[key], excluded, excludedNames, visiting);
+  }
+}
+
 // ../openapi-core/dist/core/orchestrator.js
 function runGenerationOrchestrator({ config: config2, template, hooks, runtime, createFrameworkSource }) {
   const diagnostics = new DiagnosticsCollector();
@@ -17907,11 +18022,21 @@ function runGenerationOrchestrator({ config: config2, template, hooks, runtime,
   }
   profile.defaultComponentsAndErrorsMs = performance.now() - phaseStartedAt;
   phaseStartedAt = performance.now();
-  const definedSchemas = routeProcessor.getSchemaProcessor().getDefinedSchemas();
+  const schemaProcessor = routeProcessor.getSchemaProcessor();
+  const definedSchemas = schemaProcessor.getDefinedSchemas();
   const mergedSchemas = {
     ...document.components.schemas,
     ...definedSchemas
   };
+  const internalSchemas = schemaProcessor.getInternalSchemas();
+  const patternExcludedNames = matchExcludePatterns(Object.keys(mergedSchemas), config2.excludeSchemas ?? []);
+  const allExcludedSchemas = {
+    ...internalSchemas,
+    ...Object.fromEntries(patternExcludedNames.map((name) => [name, mergedSchemas[name]]))
+  };
+  if (Object.keys(allExcludedSchemas).length > 0) {
+    applyExcludeSchemas(document, mergedSchemas, allExcludedSchemas);
+  }
   if (Object.keys(mergedSchemas).length > 0) {
     document.components.schemas = Object.fromEntries(Object.entries(mergedSchemas).sort(([a], [b]) => a.localeCompare(b, "en", { sensitivity: "base" })));
   }

package/dist/react-router/index.js

@@ -756,6 +756,17 @@ function mergeJSDocData(target, source) {
 function cleanComment(commentValue) {
   return commentValue.replace(/\*\s*/g, "").trim();
 }
+function extractInternalFlagFromComments(comments) {
+  if (!comments)
+    return false;
+  for (const comment of comments) {
+    const cleaned = cleanComment(comment.value);
+    if (/@internal\b/.test(cleaned) || /@schema\s+false\b/.test(cleaned)) {
+      return true;
+    }
+  }
+  return false;
+}
 function extractSchemaIdFromComments(comments) {
   if (!comments)
     return null;
@@ -1052,7 +1063,8 @@ var INTERNAL_OPENAPI_CONFIG_KEYS = [
   "framework",
   "next",
   "diagnostics",
-  "debug"
+  "debug",
+  "excludeSchemas"
 ];
 var AUTH_PRESET_REPLACEMENTS = {
   bearer: "BearerAuth",
@@ -1320,6 +1332,7 @@ function normalizeOpenApiConfig(template) {
     outputDir: template.outputDir ?? DEFAULT_OUTPUT_DIR,
     includeOpenApiRoutes: template.includeOpenApiRoutes ?? DEFAULT_INCLUDE_OPENAPI_ROUTES,
     ignoreRoutes: template.ignoreRoutes ?? [],
+    excludeSchemas: template.excludeSchemas ?? [],
     schemaType: template.schemaType ?? DEFAULT_RUNTIME_SCHEMA_TYPE,
     schemaBackends,
     schemaFiles: template.schemaFiles ?? [],
@@ -11732,6 +11745,8 @@ var ZodSchemaConverter = class {
   /** Schema variable names whose component name was overridden via .meta({ id }). These must
    *  NOT be copied back under the original variable name in the OpenAPI components object. */
   metaIdSchemaNames = /* @__PURE__ */ new Set();
+  /** Schema variable names marked @internal — excluded from components/schemas output. */
+  internalSchemaNames = /* @__PURE__ */ new Set();
   // Current processing context (set during file processing)
   currentFilePath;
   currentAST;
@@ -13353,7 +13368,13 @@ var ZodSchemaConverter = class {
    * Get all processed Zod schemas
    */
   getProcessedSchemas() {
-    return this.zodSchemas;
+    const result = {};
+    for (const [name, schema] of Object.entries(this.zodSchemas)) {
+      if (!this.internalSchemaNames.has(name)) {
+        result[name] = schema;
+      }
+    }
+    return result;
   }
   /**
    * Pre-scan all files to build type mappings
@@ -13405,6 +13426,15 @@ var ZodSchemaConverter = class {
               if (t10.isIdentifier(declaration.id) && declaration.init) {
                 const schemaName = declaration.id.name;
                 if (this.isZodSchema(declaration.init)) {
+                  const decl = path17.node.declaration;
+                  const allComments = [
+                    ...path17.node.leadingComments ?? [],
+                    ...decl?.leadingComments ?? [],
+                    ...declaration.leadingComments ?? []
+                  ];
+                  if (extractInternalFlagFromComments(allComments)) {
+                    this.internalSchemaNames.add(schemaName);
+                  }
                   if (!this.getStoredSchema(schemaName)) {
                     logger.debug(`Pre-processing Zod schema: ${schemaName}`);
                     this.processingSchemas.add(schemaName);
@@ -13430,6 +13460,13 @@ var ZodSchemaConverter = class {
             if (t10.isIdentifier(declaration.id) && declaration.init) {
               const schemaName = declaration.id.name;
               if (this.isZodSchema(declaration.init)) {
+                const allComments = [
+                  ...path17.node.leadingComments ?? [],
+                  ...declaration.leadingComments ?? []
+                ];
+                if (extractInternalFlagFromComments(allComments)) {
+                  this.internalSchemaNames.add(schemaName);
+                }
                 if (!this.getStoredSchema(schemaName) && !this.processingSchemas.has(schemaName)) {
                   logger.debug(`Pre-processing Zod schema: ${schemaName}`);
                   this.processingSchemas.add(schemaName);
@@ -14164,7 +14201,7 @@ function collectFirstMemberLeadingComments(interfaceDecl) {
   const firstMember = body.body?.[0];
   return firstMember?.leadingComments ?? [];
 }
-function collectAllExportedDefinitions(ast, typeDefinitions, currentFile, schemaIdAliases) {
+function collectAllExportedDefinitions(ast, typeDefinitions, currentFile, schemaIdAliases, internalSchemaNames) {
   function registerDefinition(name, entry, allComments) {
     if (!typeDefinitions[name]) {
       typeDefinitions[name] = entry;
@@ -14176,6 +14213,9 @@ function collectAllExportedDefinitions(ast, typeDefinitions, currentFile, schema
         typeDefinitions[overrideId] = entry;
       }
     }
+    if (internalSchemaNames && extractInternalFlagFromComments(allComments)) {
+      internalSchemaNames.add(name);
+    }
   }
   resolvedTraverse(ast, {
     TSTypeAliasDeclaration: (path17) => {
@@ -14655,6 +14695,7 @@ var SchemaProcessor = class {
   schemaTypes;
   isResolvingPickOmitBase = false;
   schemaIdAliases = {};
+  internalSchemaNames = /* @__PURE__ */ new Set();
   fileAccess;
   symbolResolver;
   // Track imports per file for resolving ReturnType<typeof func>
@@ -14695,7 +14736,7 @@ var SchemaProcessor = class {
   getDefinedSchemas() {
     const filteredSchemas = {};
     Object.entries(this.openapiDefinitions).forEach(([key, value]) => {
-      if (!this.schemaIdAliases[key] && !this.isGenericTypeParameter(key) && !this.isInvalidSchemaName(key) && !this.isBuiltInUtilityType(key) && !this.isFunctionSchema(key)) {
+      if (!this.schemaIdAliases[key] && !this.isGenericTypeParameter(key) && !this.isInvalidSchemaName(key) && !this.isBuiltInUtilityType(key) && !this.isFunctionSchema(key) && !this.internalSchemaNames.has(key)) {
         filteredSchemas[key] = value;
       }
     });
@@ -14705,6 +14746,22 @@ var SchemaProcessor = class {
       this.customSchemaProcessor.getDefinedSchemas()
     ]);
   }
+  getInternalSchemas() {
+    const result = {};
+    for (const name of this.internalSchemaNames) {
+      const def = this.openapiDefinitions[name];
+      if (def)
+        result[name] = def;
+    }
+    if (this.zodSchemaConverter) {
+      for (const name of this.zodSchemaConverter.internalSchemaNames) {
+        const schema = this.zodSchemaConverter.zodSchemas[name];
+        if (schema)
+          result[name] = schema;
+      }
+    }
+    return result;
+  }
   findSchemaDefinition(schemaName, contentType) {
     this.contentType = contentType;
     if (schemaName.includes("<") && schemaName.includes(">")) {
@@ -14855,7 +14912,7 @@ var SchemaProcessor = class {
    * Used when processing imported files to ensure all referenced types are available
    */
   collectAllExportedDefinitions(ast, filePath) {
-    collectAllExportedDefinitions(ast, this.typeDefinitions, filePath || this.currentFilePath, this.schemaIdAliases);
+    collectAllExportedDefinitions(ast, this.typeDefinitions, filePath || this.currentFilePath, this.schemaIdAliases, this.internalSchemaNames);
   }
   collectTypeDefinitions(ast, schemaName, filePath) {
     collectTypeDefinitions(ast, schemaName, this.typeDefinitions, filePath || this.currentFilePath);
@@ -16841,6 +16898,64 @@ function generateErrorResponsesFromConfig(document, errorConfig) {
   });
 }
 
+// ../openapi-core/dist/core/exclude-schemas.js
+function patternToRegExp(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${escaped.replace(/\*/g, ".*")}$`);
+}
+function matchExcludePatterns(names, patterns) {
+  if (patterns.length === 0)
+    return [];
+  const regexes = patterns.map(patternToRegExp);
+  return names.filter((name) => regexes.some((re) => re.test(name)));
+}
+function applyExcludeSchemas(document, mergedSchemas, excludedSchemas) {
+  const excludedNames = new Set(Object.keys(excludedSchemas));
+  if (excludedNames.size === 0)
+    return;
+  walkAndInline(document, excludedSchemas, excludedNames, /* @__PURE__ */ new Set());
+  for (const name of excludedNames) {
+    delete mergedSchemas[name];
+  }
+}
+function walkAndInline(obj, excluded, excludedNames, visiting) {
+  if (!obj || typeof obj !== "object")
+    return;
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      walkAndInline(item, excluded, excludedNames, visiting);
+    }
+    return;
+  }
+  const rec = obj;
+  const ref = rec["$ref"];
+  if (typeof ref === "string") {
+    const match = ref.match(/^#\/components\/schemas\/(.+)$/);
+    const name = match?.[1];
+    if (name && excludedNames.has(name)) {
+      if (visiting.has(name)) {
+        logger.warn(`Circular reference to internal schema "${name}", keeping $ref`);
+        return;
+      }
+      const schemaDef = excluded[name];
+      if (schemaDef) {
+        const cloned = JSON.parse(JSON.stringify(schemaDef));
+        delete rec["$ref"];
+        Object.assign(rec, cloned);
+        const newVisiting = new Set(visiting);
+        newVisiting.add(name);
+        for (const key of Object.keys(rec)) {
+          walkAndInline(rec[key], excluded, excludedNames, newVisiting);
+        }
+        return;
+      }
+    }
+  }
+  for (const key of Object.keys(rec)) {
+    walkAndInline(rec[key], excluded, excludedNames, visiting);
+  }
+}
+
 // ../openapi-core/dist/core/orchestrator.js
 function runGenerationOrchestrator({ config: config2, template, hooks, runtime, createFrameworkSource }) {
   const diagnostics = new DiagnosticsCollector();
@@ -16911,11 +17026,21 @@ function runGenerationOrchestrator({ config: config2, template, hooks, runtime,
   }
   profile.defaultComponentsAndErrorsMs = performance.now() - phaseStartedAt;
   phaseStartedAt = performance.now();
-  const definedSchemas = routeProcessor.getSchemaProcessor().getDefinedSchemas();
+  const schemaProcessor = routeProcessor.getSchemaProcessor();
+  const definedSchemas = schemaProcessor.getDefinedSchemas();
   const mergedSchemas = {
     ...document.components.schemas,
     ...definedSchemas
   };
+  const internalSchemas = schemaProcessor.getInternalSchemas();
+  const patternExcludedNames = matchExcludePatterns(Object.keys(mergedSchemas), config2.excludeSchemas ?? []);
+  const allExcludedSchemas = {
+    ...internalSchemas,
+    ...Object.fromEntries(patternExcludedNames.map((name) => [name, mergedSchemas[name]]))
+  };
+  if (Object.keys(allExcludedSchemas).length > 0) {
+    applyExcludeSchemas(document, mergedSchemas, allExcludedSchemas);
+  }
   if (Object.keys(mergedSchemas).length > 0) {
     document.components.schemas = Object.fromEntries(Object.entries(mergedSchemas).sort(([a], [b]) => a.localeCompare(b, "en", { sensitivity: "base" })));
   }

package/dist/vite/index.js

@@ -756,6 +756,17 @@ function mergeJSDocData(target, source) {
 function cleanComment(commentValue) {
   return commentValue.replace(/\*\s*/g, "").trim();
 }
+function extractInternalFlagFromComments(comments) {
+  if (!comments)
+    return false;
+  for (const comment of comments) {
+    const cleaned = cleanComment(comment.value);
+    if (/@internal\b/.test(cleaned) || /@schema\s+false\b/.test(cleaned)) {
+      return true;
+    }
+  }
+  return false;
+}
 function extractSchemaIdFromComments(comments) {
   if (!comments)
     return null;
@@ -1052,7 +1063,8 @@ var INTERNAL_OPENAPI_CONFIG_KEYS = [
   "framework",
   "next",
   "diagnostics",
-  "debug"
+  "debug",
+  "excludeSchemas"
 ];
 var AUTH_PRESET_REPLACEMENTS = {
   bearer: "BearerAuth",
@@ -1320,6 +1332,7 @@ function normalizeOpenApiConfig(template) {
     outputDir: template.outputDir ?? DEFAULT_OUTPUT_DIR,
     includeOpenApiRoutes: template.includeOpenApiRoutes ?? DEFAULT_INCLUDE_OPENAPI_ROUTES,
     ignoreRoutes: template.ignoreRoutes ?? [],
+    excludeSchemas: template.excludeSchemas ?? [],
     schemaType: template.schemaType ?? DEFAULT_RUNTIME_SCHEMA_TYPE,
     schemaBackends,
     schemaFiles: template.schemaFiles ?? [],
@@ -11732,6 +11745,8 @@ var ZodSchemaConverter = class {
   /** Schema variable names whose component name was overridden via .meta({ id }). These must
    *  NOT be copied back under the original variable name in the OpenAPI components object. */
   metaIdSchemaNames = /* @__PURE__ */ new Set();
+  /** Schema variable names marked @internal — excluded from components/schemas output. */
+  internalSchemaNames = /* @__PURE__ */ new Set();
   // Current processing context (set during file processing)
   currentFilePath;
   currentAST;
@@ -13353,7 +13368,13 @@ var ZodSchemaConverter = class {
    * Get all processed Zod schemas
    */
   getProcessedSchemas() {
-    return this.zodSchemas;
+    const result = {};
+    for (const [name, schema] of Object.entries(this.zodSchemas)) {
+      if (!this.internalSchemaNames.has(name)) {
+        result[name] = schema;
+      }
+    }
+    return result;
   }
   /**
    * Pre-scan all files to build type mappings
@@ -13405,6 +13426,15 @@ var ZodSchemaConverter = class {
               if (t10.isIdentifier(declaration.id) && declaration.init) {
                 const schemaName = declaration.id.name;
                 if (this.isZodSchema(declaration.init)) {
+                  const decl = path17.node.declaration;
+                  const allComments = [
+                    ...path17.node.leadingComments ?? [],
+                    ...decl?.leadingComments ?? [],
+                    ...declaration.leadingComments ?? []
+                  ];
+                  if (extractInternalFlagFromComments(allComments)) {
+                    this.internalSchemaNames.add(schemaName);
+                  }
                   if (!this.getStoredSchema(schemaName)) {
                     logger.debug(`Pre-processing Zod schema: ${schemaName}`);
                     this.processingSchemas.add(schemaName);
@@ -13430,6 +13460,13 @@ var ZodSchemaConverter = class {
             if (t10.isIdentifier(declaration.id) && declaration.init) {
               const schemaName = declaration.id.name;
               if (this.isZodSchema(declaration.init)) {
+                const allComments = [
+                  ...path17.node.leadingComments ?? [],
+                  ...declaration.leadingComments ?? []
+                ];
+                if (extractInternalFlagFromComments(allComments)) {
+                  this.internalSchemaNames.add(schemaName);
+                }
                 if (!this.getStoredSchema(schemaName) && !this.processingSchemas.has(schemaName)) {
                   logger.debug(`Pre-processing Zod schema: ${schemaName}`);
                   this.processingSchemas.add(schemaName);
@@ -14164,7 +14201,7 @@ function collectFirstMemberLeadingComments(interfaceDecl) {
   const firstMember = body.body?.[0];
   return firstMember?.leadingComments ?? [];
 }
-function collectAllExportedDefinitions(ast, typeDefinitions, currentFile, schemaIdAliases) {
+function collectAllExportedDefinitions(ast, typeDefinitions, currentFile, schemaIdAliases, internalSchemaNames) {
   function registerDefinition(name, entry, allComments) {
     if (!typeDefinitions[name]) {
       typeDefinitions[name] = entry;
@@ -14176,6 +14213,9 @@ function collectAllExportedDefinitions(ast, typeDefinitions, currentFile, schema
         typeDefinitions[overrideId] = entry;
       }
     }
+    if (internalSchemaNames && extractInternalFlagFromComments(allComments)) {
+      internalSchemaNames.add(name);
+    }
   }
   resolvedTraverse(ast, {
     TSTypeAliasDeclaration: (path17) => {
@@ -14655,6 +14695,7 @@ var SchemaProcessor = class {
   schemaTypes;
   isResolvingPickOmitBase = false;
   schemaIdAliases = {};
+  internalSchemaNames = /* @__PURE__ */ new Set();
   fileAccess;
   symbolResolver;
   // Track imports per file for resolving ReturnType<typeof func>
@@ -14695,7 +14736,7 @@ var SchemaProcessor = class {
   getDefinedSchemas() {
     const filteredSchemas = {};
     Object.entries(this.openapiDefinitions).forEach(([key, value]) => {
-      if (!this.schemaIdAliases[key] && !this.isGenericTypeParameter(key) && !this.isInvalidSchemaName(key) && !this.isBuiltInUtilityType(key) && !this.isFunctionSchema(key)) {
+      if (!this.schemaIdAliases[key] && !this.isGenericTypeParameter(key) && !this.isInvalidSchemaName(key) && !this.isBuiltInUtilityType(key) && !this.isFunctionSchema(key) && !this.internalSchemaNames.has(key)) {
         filteredSchemas[key] = value;
       }
     });
@@ -14705,6 +14746,22 @@ var SchemaProcessor = class {
       this.customSchemaProcessor.getDefinedSchemas()
     ]);
   }
+  getInternalSchemas() {
+    const result = {};
+    for (const name of this.internalSchemaNames) {
+      const def = this.openapiDefinitions[name];
+      if (def)
+        result[name] = def;
+    }
+    if (this.zodSchemaConverter) {
+      for (const name of this.zodSchemaConverter.internalSchemaNames) {
+        const schema = this.zodSchemaConverter.zodSchemas[name];
+        if (schema)
+          result[name] = schema;
+      }
+    }
+    return result;
+  }
   findSchemaDefinition(schemaName, contentType) {
     this.contentType = contentType;
     if (schemaName.includes("<") && schemaName.includes(">")) {
@@ -14855,7 +14912,7 @@ var SchemaProcessor = class {
    * Used when processing imported files to ensure all referenced types are available
    */
   collectAllExportedDefinitions(ast, filePath) {
-    collectAllExportedDefinitions(ast, this.typeDefinitions, filePath || this.currentFilePath, this.schemaIdAliases);
+    collectAllExportedDefinitions(ast, this.typeDefinitions, filePath || this.currentFilePath, this.schemaIdAliases, this.internalSchemaNames);
   }
   collectTypeDefinitions(ast, schemaName, filePath) {
     collectTypeDefinitions(ast, schemaName, this.typeDefinitions, filePath || this.currentFilePath);
@@ -16841,6 +16898,64 @@ function generateErrorResponsesFromConfig(document, errorConfig) {
   });
 }
 
+// ../openapi-core/dist/core/exclude-schemas.js
+function patternToRegExp(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${escaped.replace(/\*/g, ".*")}$`);
+}
+function matchExcludePatterns(names, patterns) {
+  if (patterns.length === 0)
+    return [];
+  const regexes = patterns.map(patternToRegExp);
+  return names.filter((name) => regexes.some((re) => re.test(name)));
+}
+function applyExcludeSchemas(document, mergedSchemas, excludedSchemas) {
+  const excludedNames = new Set(Object.keys(excludedSchemas));
+  if (excludedNames.size === 0)
+    return;
+  walkAndInline(document, excludedSchemas, excludedNames, /* @__PURE__ */ new Set());
+  for (const name of excludedNames) {
+    delete mergedSchemas[name];
+  }
+}
+function walkAndInline(obj, excluded, excludedNames, visiting) {
+  if (!obj || typeof obj !== "object")
+    return;
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      walkAndInline(item, excluded, excludedNames, visiting);
+    }
+    return;
+  }
+  const rec = obj;
+  const ref = rec["$ref"];
+  if (typeof ref === "string") {
+    const match = ref.match(/^#\/components\/schemas\/(.+)$/);
+    const name = match?.[1];
+    if (name && excludedNames.has(name)) {
+      if (visiting.has(name)) {
+        logger.warn(`Circular reference to internal schema "${name}", keeping $ref`);
+        return;
+      }
+      const schemaDef = excluded[name];
+      if (schemaDef) {
+        const cloned = JSON.parse(JSON.stringify(schemaDef));
+        delete rec["$ref"];
+        Object.assign(rec, cloned);
+        const newVisiting = new Set(visiting);
+        newVisiting.add(name);
+        for (const key of Object.keys(rec)) {
+          walkAndInline(rec[key], excluded, excludedNames, newVisiting);
+        }
+        return;
+      }
+    }
+  }
+  for (const key of Object.keys(rec)) {
+    walkAndInline(rec[key], excluded, excludedNames, visiting);
+  }
+}
+
 // ../openapi-core/dist/core/orchestrator.js
 function runGenerationOrchestrator({ config: config2, template, hooks, runtime, createFrameworkSource }) {
   const diagnostics = new DiagnosticsCollector();
@@ -16911,11 +17026,21 @@ function runGenerationOrchestrator({ config: config2, template, hooks, runtime,
   }
   profile.defaultComponentsAndErrorsMs = performance.now() - phaseStartedAt;
   phaseStartedAt = performance.now();
-  const definedSchemas = routeProcessor.getSchemaProcessor().getDefinedSchemas();
+  const schemaProcessor = routeProcessor.getSchemaProcessor();
+  const definedSchemas = schemaProcessor.getDefinedSchemas();
   const mergedSchemas = {
     ...document.components.schemas,
     ...definedSchemas
   };
+  const internalSchemas = schemaProcessor.getInternalSchemas();
+  const patternExcludedNames = matchExcludePatterns(Object.keys(mergedSchemas), config2.excludeSchemas ?? []);
+  const allExcludedSchemas = {
+    ...internalSchemas,
+    ...Object.fromEntries(patternExcludedNames.map((name) => [name, mergedSchemas[name]]))
+  };
+  if (Object.keys(allExcludedSchemas).length > 0) {
+    applyExcludeSchemas(document, mergedSchemas, allExcludedSchemas);
+  }
   if (Object.keys(mergedSchemas).length > 0) {
     document.components.schemas = Object.fromEntries(Object.entries(mergedSchemas).sort(([a], [b]) => a.localeCompare(b, "en", { sensitivity: "base" })));
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-openapi-gen",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "Automatically generate OpenAPI 3.0, 3.1, and 3.2 documentation from Next.js projects, with support for Zod schemas, TypeScript types, and reusable OpenAPI fragments.",
   "keywords": [
     "api",