feat: exclude internal schemas from components via @internal tag and excludeSchemas config (#139)

daniel-rose · web-flow · commit a2b79b106f69 · 2026-05-17T22:40:25.000+02:00
diff --git a/README.md b/README.md
@@ -276,19 +276,20 @@ Version guidance:
 
 ### Important options
 
-| Option                                | Purpose                                                          |
-| ------------------------------------- | ---------------------------------------------------------------- |
-| `openapi`                             | Target `3.0.0`, `3.1.0`, or `3.2.0` output                       |
-| `apiDir`                              | Route directory to scan                                          |
-| `routerType`                          | `"app"` or `"pages"`                                             |
-| `schemaDir`                           | Directory or directories to search for schemas/types             |
-| `schemaType`                          | `"zod"`, `"typescript"`, or both                                 |
-| `schemaFiles`                         | YAML/JSON OpenAPI fragments to merge into the generated document |
-| `includeOpenApiRoutes`                | Only include handlers tagged with `@openapi`                     |
-| `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     |
+| Option                                | Purpose                                                                                 |
+| ------------------------------------- | --------------------------------------------------------------------------------------- |
+| `openapi`                             | Target `3.0.0`, `3.1.0`, or `3.2.0` output                                              |
+| `apiDir`                              | Route directory to scan                                                                 |
+| `routerType`                          | `"app"` or `"pages"`                                                                    |
+| `schemaDir`                           | Directory or directories to search for schemas/types                                    |
+| `schemaType`                          | `"zod"`, `"typescript"`, or both                                                        |
+| `schemaFiles`                         | YAML/JSON OpenAPI fragments to merge into the generated document                        |
+| `includeOpenApiRoutes`                | Only include handlers tagged with `@openapi`                                            |
+| `ignoreRoutes`                        | Exclude routes with wildcard support                                                    |
+| `excludeSchemas`                      | Exclude internal schemas from `components/schemas` by name or glob (e.g. `["*Params"]`) |
+| `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).
@@ -315,6 +316,7 @@ patterns, see [docs/getting-started.md](./docs/getting-started.md).
 | `@openapi`                 | Explicit inclusion marker when `includeOpenApiRoutes` is enabled                                        |
 | `@openapi-override`        | Deep-merge extra OpenAPI fields onto the operation                                                      |
 | `@ignore`                  | Exclude a route from generation                                                                         |
+| `@internal`                | Exclude a schema/type declaration from `components/schemas`                                             |
 | `@method`                  | Required HTTP method tag for Pages Router handlers                                                      |
 
 For the complete tag guide and usage recipes, see
diff --git a/docs/jsdoc-reference.md b/docs/jsdoc-reference.md
@@ -645,6 +645,54 @@ export interface AudioInterface {
 In both cases, the component is registered as `Audio` and cross-type references resolve correctly
 to `#/components/schemas/Audio`.
 
+## Excluding internal schemas from components
+
+Inline Zod or TypeScript schemas used only as route-internal implementation details (path/query param
+shapes, bulk-payload bounds, etc.) are emitted into `components/schemas` by default. Two mechanisms
+let you suppress them.
+
+### Per-schema: `@internal` JSDoc tag
+
+Add `/** @internal */` as a leading comment on any Zod `const` declaration or TypeScript
+`type`/`interface`:
+
+```ts
+/** @internal */
+const productIdParamsSchema = z.object({
+  id: z.coerce.number().int().positive(),
+});
+
+/** @internal */
+export type ProductIdParams = z.infer<typeof productIdParamsSchema>;
+```
+
+Both forms suppress the schema from `components/schemas`. If the schema is still referenced by a
+route (e.g. via `@pathParams`), the `$ref` is automatically replaced with the inlined schema content
+so the generated spec remains valid.
+
+`@schema false` is accepted as an alias for `@internal`.
+
+### Project-wide: `excludeSchemas` config
+
+Add `excludeSchemas` to your `openapi-gen.config.ts` (or `next.openapi.json`) to exclude schemas by
+exact name or simple glob (`*`):
+
+```ts
+// openapi-gen.config.ts
+export default defineConfig({
+  // ...
+  excludeSchemas: ["*Params", "productBulkSchema"],
+});
+```
+
+| Pattern                   | Matches                           |
+| ------------------------- | --------------------------------- |
+| `"productIdParamsSchema"` | Exact name                        |
+| `"*Params"`               | Any name ending with `Params`     |
+| `"Internal*"`             | Any name starting with `Internal` |
+
+References to excluded schemas in route operations are inlined automatically.
+
 ## Related guides
 
 - [Getting started and configuration](./getting-started.md)
diff --git a/packages/openapi-core/src/config/normalize.ts b/packages/openapi-core/src/config/normalize.ts
@@ -132,6 +132,7 @@ export function normalizeOpenApiConfig(
     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 ?? [],
diff --git a/packages/openapi-core/src/core/exclude-schemas.ts b/packages/openapi-core/src/core/exclude-schemas.ts
@@ -0,0 +1,74 @@
+import { logger } from "../shared/logger.js";
+import type { OpenApiDocument, OpenApiSchema } from "../shared/types.js";
+
+function patternToRegExp(pattern: string): RegExp {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${escaped.replace(/\*/g, ".*")}$`);
+}
+
+export function matchExcludePatterns(names: string[], patterns: string[]): string[] {
+  if (patterns.length === 0) return [];
+  const regexes = patterns.map(patternToRegExp);
+  return names.filter((name) => regexes.some((re) => re.test(name)));
+}
+
+export function applyExcludeSchemas(
+  document: OpenApiDocument,
+  mergedSchemas: Record<string, unknown>,
+  excludedSchemas: Record<string, OpenApiSchema>,
+): void {
+  const excludedNames = new Set(Object.keys(excludedSchemas));
+  if (excludedNames.size === 0) return;
+
+  walkAndInline(document, excludedSchemas, excludedNames, new Set());
+
+  for (const name of excludedNames) {
+    delete mergedSchemas[name];
+  }
+}
+
+function walkAndInline(
+  obj: unknown,
+  excluded: Record<string, OpenApiSchema>,
+  excludedNames: Set<string>,
+  visiting: Set<string>,
+): void {
+  if (!obj || typeof obj !== "object") return;
+
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      walkAndInline(item, excluded, excludedNames, visiting);
+    }
+    return;
+  }
+
+  const rec = obj as Record<string, unknown>;
+  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)) as Record<string, unknown>;
+        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);
+  }
+}
diff --git a/packages/openapi-core/src/core/orchestrator.ts b/packages/openapi-core/src/core/orchestrator.ts
@@ -22,6 +22,7 @@ import {
   type GenerationPerformanceProfile,
 } from "./performance.js";
 import type { SharedGenerationRuntime } from "./runtime.js";
+import { applyExcludeSchemas, matchExcludePatterns } from "./exclude-schemas.js";
 export type OrchestratorPerformanceProfile = GenerationPerformanceProfile & {
   scanRoutesMs: number;
 };
@@ -132,11 +133,28 @@ export function runGenerationOrchestrator({
   profile.defaultComponentsAndErrorsMs = performance.now() - phaseStartedAt;
 
   phaseStartedAt = performance.now();
-  const definedSchemas = routeProcessor.getSchemaProcessor().getDefinedSchemas();
+  const schemaProcessor = routeProcessor.getSchemaProcessor();
+  const definedSchemas = schemaProcessor.getDefinedSchemas();
   const mergedSchemas: Record<string, unknown> = {
     ...document.components.schemas,
     ...definedSchemas,
   };
+
+  const internalSchemas = schemaProcessor.getInternalSchemas();
+  const patternExcludedNames = matchExcludePatterns(
+    Object.keys(mergedSchemas),
+    config.excludeSchemas ?? [],
+  );
+  const allExcludedSchemas = {
+    ...internalSchemas,
+    ...Object.fromEntries(
+      patternExcludedNames.map((name) => [name, mergedSchemas[name] as Record<string, unknown>]),
+    ),
+  };
+  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]) =>
diff --git a/packages/openapi-core/src/schema/typescript/schema-discovery.ts b/packages/openapi-core/src/schema/typescript/schema-discovery.ts
@@ -4,7 +4,10 @@ import * as t from "@babel/types";
 
 import { traverse } from "../../shared/babel-traverse.js";
 import { resolveTypeScriptModule } from "../../shared/typescript-project.js";
-import { extractSchemaIdFromComments } from "../../shared/utils.js";
+import {
+  extractInternalFlagFromComments,
+  extractSchemaIdFromComments,
+} from "../../shared/utils.js";
 
 type TypeDefinitions = Record<string, any>;
 
@@ -116,6 +119,7 @@ export function collectAllExportedDefinitions(
   typeDefinitions: TypeDefinitions,
   currentFile: string,
   schemaIdAliases?: Record<string, string>,
+  internalSchemaNames?: Set<string>,
 ): void {
   function registerDefinition(
     name: string,
@@ -132,6 +136,9 @@ export function collectAllExportedDefinitions(
         typeDefinitions[overrideId] = entry;
       }
     }
+    if (internalSchemaNames && extractInternalFlagFromComments(allComments)) {
+      internalSchemaNames.add(name);
+    }
   }
 
   traverse(ast, {
diff --git a/packages/openapi-core/src/schema/typescript/schema-processor.ts b/packages/openapi-core/src/schema/typescript/schema-processor.ts
@@ -84,6 +84,7 @@ export class SchemaProcessor {
   private schemaTypes: SchemaType[];
   private isResolvingPickOmitBase: boolean = false;
   private schemaIdAliases: Record<string, string> = {};
+  private internalSchemaNames: Set<string> = new Set();
   private readonly fileAccess: SchemaProcessorFileAccess;
   private readonly symbolResolver: SymbolResolver;
 
@@ -147,7 +148,8 @@ export class SchemaProcessor {
         !this.isGenericTypeParameter(key) &&
         !this.isInvalidSchemaName(key) &&
         !this.isBuiltInUtilityType(key) &&
-        !this.isFunctionSchema(key)
+        !this.isFunctionSchema(key) &&
+        !this.internalSchemaNames.has(key)
       ) {
         filteredSchemas[key] = value;
       }
@@ -160,6 +162,21 @@ export class SchemaProcessor {
     ]);
   }
 
+  public getInternalSchemas(): Record<string, OpenAPIDefinition> {
+    const result: Record<string, OpenAPIDefinition> = {};
+    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;
+  }
+
   public findSchemaDefinition(schemaName: string, contentType: ContentType): OpenAPIDefinition {
     // Assign type that is actually processed
     this.contentType = contentType;
@@ -354,6 +371,7 @@ export class SchemaProcessor {
       this.typeDefinitions,
       filePath || this.currentFilePath,
       this.schemaIdAliases,
+      this.internalSchemaNames,
     );
   }
 
diff --git a/packages/openapi-core/src/schema/zod/zod-converter.ts b/packages/openapi-core/src/schema/zod/zod-converter.ts
@@ -4,7 +4,7 @@ import type { NodePath } from "@babel/traverse";
 import * as t from "@babel/types";
 
 import { traverse } from "../../shared/babel-traverse.js";
-import { parseTypeScriptFile } from "../../shared/utils.js";
+import { extractInternalFlagFromComments, parseTypeScriptFile } from "../../shared/utils.js";
 import { logger } from "../../shared/logger.js";
 import { SymbolResolver } from "../../shared/symbol-resolver.js";
 import { DrizzleZodProcessor } from "./drizzle-zod-processor.js";
@@ -78,6 +78,8 @@ export class ZodSchemaConverter {
   /** 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: Set<string> = new Set();
+  /** Schema variable names marked @internal — excluded from components/schemas output. */
+  internalSchemaNames: Set<string> = new Set();
   // Current processing context (set during file processing)
   currentFilePath?: string;
   currentAST?: t.File;
@@ -2272,7 +2274,13 @@ export class ZodSchemaConverter {
    * Get all processed Zod schemas
    */
   getProcessedSchemas(): Record<string, OpenApiSchema> {
-    return this.zodSchemas;
+    const result: Record<string, OpenApiSchema> = {};
+    for (const [name, schema] of Object.entries(this.zodSchemas)) {
+      if (!this.internalSchemaNames.has(name)) {
+        result[name] = schema;
+      }
+    }
+    return result;
   }
 
   /**
@@ -2346,6 +2354,15 @@ export class ZodSchemaConverter {
 
                 // Check if is Zod schema
                 if (this.isZodSchema(declaration.init)) {
+                  const decl = path.node.declaration;
+                  const allComments = [
+                    ...(path.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);
@@ -2371,6 +2388,13 @@ export class ZodSchemaConverter {
             if (t.isIdentifier(declaration.id) && declaration.init) {
               const schemaName = declaration.id.name;
               if (this.isZodSchema(declaration.init)) {
+                const allComments = [
+                  ...(path.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);
diff --git a/packages/openapi-core/src/shared/types.ts b/packages/openapi-core/src/shared/types.ts
@@ -63,6 +63,7 @@ export type OpenApiConfig = {
   outputDir: string;
   includeOpenApiRoutes: boolean;
   ignoreRoutes?: string[] | undefined;
+  excludeSchemas?: string[] | undefined;
   schemaType: SchemaType | SchemaType[]; // Support both single type and array of types
   schemaFiles?: string[] | undefined; // Array of custom OpenAPI schema files (YAML/JSON)
   defaultResponseSet?: string | undefined;
@@ -173,6 +174,7 @@ export type OpenApiTemplate = OpenApiDocument & {
   outputDir?: string | undefined;
   includeOpenApiRoutes?: boolean | undefined;
   ignoreRoutes?: string[] | undefined;
+  excludeSchemas?: string[] | undefined;
   schemaType?: SchemaType | SchemaType[] | undefined;
   schemaFiles?: string[] | undefined;
   defaultResponseSet?: string | undefined;
diff --git a/packages/openapi-core/src/shared/utils.ts b/packages/openapi-core/src/shared/utils.ts
diff --git a/tests/integration/generator/exclude-schemas.test.ts b/tests/integration/generator/exclude-schemas.test.ts
diff --git a/tests/unit/core/exclude-schemas.test.ts b/tests/unit/core/exclude-schemas.test.ts
diff --git a/tests/unit/shared/utils.test.ts b/tests/unit/shared/utils.test.ts
