next-openapi-gen 1.2.2 → 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",
@@ -12142,6 +12155,11 @@ var ZodSchemaConverter = class {
   schemaNameToFiles = /* @__PURE__ */ new Map();
   /** Per-file import alias for the `zod` module (`import { z as zod }` sets this to `"zod"`). */
   zodImportAlias = /* @__PURE__ */ new Map();
+  /** 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;
@@ -12168,7 +12186,14 @@ var ZodSchemaConverter = class {
     }
     logger.debug(`Looking for Zod schema: ${schemaName}`);
     const requestedSchemaName = schemaName;
-    const mappedSchemaName = this.typeToSchemaMapping[schemaName];
+    let mappedSchemaName = this.typeToSchemaMapping[schemaName];
+    if (!mappedSchemaName) {
+      const candidate = this.deriveSchemaNameByConvention(schemaName);
+      if (candidate && this.locateSchemaByConvention(candidate)) {
+        this.typeToSchemaMapping[schemaName] = candidate;
+        mappedSchemaName = candidate;
+      }
+    }
     if (mappedSchemaName) {
       logger.debug(`Type '${schemaName}' is mapped to schema '${mappedSchemaName}'`);
       schemaName = mappedSchemaName;
@@ -12218,7 +12243,7 @@ var ZodSchemaConverter = class {
       this.processingSchemas.delete(schemaName);
       if (mappedSchemaName && requestedSchemaName !== schemaName) {
         const resolvedReference = this.getSchemaReferenceName(schemaName, this.currentContentType);
-        if (this.zodSchemas[resolvedReference] && !this.zodSchemas[requestedSchemaName]) {
+        if (!this.metaIdSchemaNames.has(requestedSchemaName) && this.zodSchemas[resolvedReference] && !this.zodSchemas[requestedSchemaName]) {
           this.zodSchemas[requestedSchemaName] = this.zodSchemas[resolvedReference];
         }
         this.schemaVariantRefs.set(this.getVariantKey(requestedSchemaName, this.currentContentType), this.zodSchemas[requestedSchemaName] ? requestedSchemaName : resolvedReference);
@@ -13756,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
@@ -13808,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);
@@ -13833,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);
@@ -13875,15 +13922,57 @@ var ZodSchemaConverter = class {
     if (finalName !== schemaName) {
       this.indexSchemaName(finalName, filePath);
     }
-    if (!this.getStoredSchema(finalName)) {
+    if (!this.zodSchemas[finalName]) {
       if (overrideId && overrideId !== schemaName) {
         this.typeToSchemaMapping[schemaName] = overrideId;
+        this.metaIdSchemaNames.add(schemaName);
+        if (this.typeToSchemaMapping[overrideId] === schemaName) {
+          delete this.typeToSchemaMapping[overrideId];
+        }
       }
-      this.storeResolvedSchema(finalName, schema);
+      const variantKey = this.getVariantKey(finalName, this.currentContentType);
+      this.zodSchemas[finalName] = schema;
+      this.schemaVariantRefs.set(variantKey, finalName);
     } else {
       logger.warn(`Schema component name '${overrideId ?? finalName}' conflicts with an existing schema, ignoring .meta({ id }) on '${schemaName}'`);
     }
   }
+  /**
+   * Derives the conventional Zod schema name from a TypeScript type name.
+   * e.g. "Slider" → "sliderSchema", "SliderItem" → "sliderItemSchema".
+   * Returns null when the input is already a schema name or is not PascalCase.
+   */
+  deriveSchemaNameByConvention(typeName) {
+    if (!typeName || !/^[A-Z]/.test(typeName) || typeName.endsWith("Schema")) {
+      return null;
+    }
+    return typeName[0].toLowerCase() + typeName.slice(1) + "Schema";
+  }
+  /**
+   * Checks whether a Zod schema with the given name is present in schemaDirs
+   * WITHOUT populating the processed-schema cache. A file-content substring check
+   * (the same heuristic used by processFileForZodSchema) is sufficient here: we
+   * only want to know whether the candidate *might* live in schemaDirs so that the
+   * convention mapping can be registered; the actual processing happens later in
+   * the normal convertZodSchemaToOpenApi lookup flow.
+   */
+  locateSchemaByConvention(candidate) {
+    if (this.schemaNameToFiles.has(candidate)) {
+      return true;
+    }
+    for (const dir of this.schemaDirs) {
+      for (const filePath of this.getSchemaFiles(dir)) {
+        try {
+          const content = this.fileAccess.readFileSync(filePath, "utf-8");
+          if (content.includes(candidate)) {
+            return true;
+          }
+        } catch {
+        }
+      }
+    }
+    return false;
+  }
   /**
    * Check if node is Zod schema
    */
@@ -14525,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;
@@ -14537,6 +14626,9 @@ function collectAllExportedDefinitions(ast, typeDefinitions, currentFile, schema
         typeDefinitions[overrideId] = entry;
       }
     }
+    if (internalSchemaNames && extractInternalFlagFromComments(allComments)) {
+      internalSchemaNames.add(name);
+    }
   }
   resolvedTraverse(ast, {
     TSTypeAliasDeclaration: (path25) => {
@@ -15016,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>
@@ -15056,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;
       }
     });
@@ -15066,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(">")) {
@@ -15216,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);
@@ -17202,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();
@@ -17272,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" })));
   }