next-openapi-gen 1.2.3 → 1.4.0

package/dist/vite/index.js

@@ -388,7 +388,7 @@ function parseJSDocBlock(commentValue, filePath) {
   result.cookieType = extractTypeFromComment(normalizedComment, "@cookie");
   const authValue = extractLineValue(normalizedComment, "@auth");
   if (authValue) {
-    result.auth = performAuthPresetReplacements(authValue);
+    result.auth = authValue;
   }
   const querystring = parseQuerystringTag(normalizedComment);
   if (querystring) {
@@ -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,16 +1063,18 @@ var INTERNAL_OPENAPI_CONFIG_KEYS = [
   "framework",
   "next",
   "diagnostics",
-  "debug"
+  "debug",
+  "authPresets",
+  "excludeSchemas"
 ];
-var AUTH_PRESET_REPLACEMENTS = {
+var DEFAULT_AUTH_PRESET_REPLACEMENTS = {
   bearer: "BearerAuth",
   basic: "BasicAuth",
   apikey: "ApiKeyAuth"
 };
-function performAuthPresetReplacements(authValue) {
+function performAuthPresetReplacements(authValue, presets = DEFAULT_AUTH_PRESET_REPLACEMENTS) {
   const authParts = authValue.split(",").map((part) => part.trim());
-  const mappedParts = authParts.map((part) => AUTH_PRESET_REPLACEMENTS[part.toLowerCase()] || part);
+  const mappedParts = authParts.map((part) => presets[part.toLowerCase()] || part);
   return mappedParts.join(",");
 }
 function getOperationId(routePath, method) {
@@ -1320,6 +1333,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 ?? [],
@@ -1333,6 +1347,7 @@ function normalizeOpenApiConfig(template) {
       adapterPath: template.next?.adapterPath
     },
     diagnostics: template.diagnostics ?? { enabled: DEFAULT_DIAGNOSTICS_ENABLED },
+    authPresets: { ...DEFAULT_AUTH_PRESET_REPLACEMENTS, ...template.authPresets },
     debug: template.debug ?? DEFAULT_DEBUG
   };
 }
@@ -1814,8 +1829,10 @@ function downgradeSchemaForOpenApi30(schema, mediaTypeName) {
     const nullableBranch = nextSchema.anyOf.find((item) => item.type === "null");
     const baseBranch = nextSchema.anyOf.find((item) => item.type !== "null");
     if (nullableBranch && baseBranch) {
+      const { anyOf: _anyOf, ...outerMeta } = nextSchema;
       nextSchema = {
         ...structuredClone(baseBranch),
+        ...outerMeta,
         nullable: true
       };
     }
@@ -3690,7 +3707,7 @@ function processZodLiteral(node, context) {
     return { type: "string", enum: [arg.value] };
   }
   if (t8.isNumericLiteral(arg)) {
-    return { type: "number", enum: [arg.value] };
+    return { type: Number.isInteger(arg.value) ? "integer" : "number", enum: [arg.value] };
   }
   if (t8.isBooleanLiteral(arg)) {
     return { type: "boolean", enum: [arg.value] };
@@ -3706,7 +3723,7 @@ function processZodLiteral(node, context) {
     if (typeof value === "string")
       return { type: "string", enum: [value] };
     if (typeof value === "number")
-      return { type: "number", enum: [value] };
+      return { type: Number.isInteger(value) ? "integer" : "number", enum: [value] };
     if (typeof value === "boolean")
       return { type: "boolean", enum: [value] };
     if (value === null)
@@ -3801,7 +3818,7 @@ function processZodTuple(node, processNode, context) {
     if (t8.isIdentifier(node.arguments[0]) && context?.resolveConstArrayValues) {
       const values = context.resolveConstArrayValues(node.arguments[0].name);
       if (values && values.length > 0) {
-        const prefixItems = values.map((value) => typeof value === "number" ? { type: "number", enum: [value] } : { type: "string", enum: [value] });
+        const prefixItems = values.map((value) => typeof value === "number" ? { type: Number.isInteger(value) ? "integer" : "number", enum: [value] } : { type: "string", enum: [value] });
         return {
           type: "array",
           prefixItems,
@@ -3845,7 +3862,7 @@ function processZodUnion(node, processNode, context) {
     if (t8.isIdentifier(node.arguments[0]) && context?.resolveConstArrayValues) {
       const values = context.resolveConstArrayValues(node.arguments[0].name);
       if (values && values.length > 0) {
-        const type = typeof values[0] === "number" ? "number" : "string";
+        const type = typeof values[0] === "number" ? Number.isInteger(values[0]) ? "integer" : "number" : "string";
         return { type, enum: values };
       }
     }
@@ -11292,8 +11309,17 @@ var ZodRuntimeExporter = class {
         return node.arguments[0] ? literal(this.buildLiteralValue(node.arguments[0])) : null;
       case "enum":
         return this.buildEnum(node);
-      case "array":
-        return node.arguments[0] && isProcessableNode(node.arguments[0]) ? array(this.buildSchema(node.arguments[0]) ?? unknown()) : array(unknown());
+      case "array": {
+        const arg = node.arguments[0];
+        if (!arg || !isProcessableNode(arg)) {
+          return array(unknown());
+        }
+        const itemSchema = this.buildSchema(arg);
+        if (!itemSchema) {
+          return null;
+        }
+        return array(itemSchema);
+      }
       case "strictObject": {
         const base = this.buildObject(node);
         return base && typeof base.strict === "function" ? base.strict() : base;
@@ -11425,13 +11451,17 @@ var ZodRuntimeExporter = class {
     if (node.arguments.length === 0 || !t9.isArrayExpression(node.arguments[0])) {
       return tuple([]);
     }
-    const items = node.arguments[0].elements.flatMap((element) => {
+    const items = [];
+    for (const element of node.arguments[0].elements) {
       if (!isProcessableNode(element)) {
-        return [];
+        return null;
       }
       const schema = this.buildSchema(element);
-      return schema ? [schema] : [];
-    });
+      if (!schema) {
+        return null;
+      }
+      items.push(schema);
+    }
     return tuple(items);
   }
   buildTemplateLiteral(node) {
@@ -11732,6 +11762,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;
@@ -12041,7 +12073,12 @@ var ZodSchemaConverter = class {
             if (this.isZodSchema(path17.node.init)) {
               const schema = this.processZodNode(path17.node.init);
               if (schema) {
-                this.storeResolvedSchema(schemaName, schema);
+                const overrideId = this.extractMetaIdFromNode(path17.node.init);
+                if (overrideId) {
+                  this.applyMetaIdOverride(schemaName, schema, overrideId, filePath);
+                } else {
+                  this.storeResolvedSchema(schemaName, schema);
+                }
               }
               return;
             }
@@ -12384,8 +12421,15 @@ var ZodSchemaConverter = class {
         };
         switch (methodName) {
           case "optional":
+            break;
           case "nullable":
           case "nullish":
+            schema = {
+              anyOf: [
+                { $ref: `#/components/schemas/${this.getSchemaReferenceName(schemaName)}` },
+                { type: "null" }
+              ]
+            };
             break;
           case "describe":
             if (node.arguments.length > 0 && t10.isStringLiteral(node.arguments[0])) {
@@ -12903,12 +12947,16 @@ var ZodSchemaConverter = class {
       case "optional":
         break;
       case "nullable":
-        if (!schema.allOf) {
+        if (schema.allOf) {
+          schema = { anyOf: [...schema.allOf, { type: "null" }] };
+        } else {
           schema.nullable = true;
         }
         break;
       case "nullish":
-        if (!schema.allOf) {
+        if (schema.allOf) {
+          schema = { anyOf: [...schema.allOf, { type: "null" }] };
+        } else {
           schema.nullable = true;
         }
         break;
@@ -13353,7 +13401,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,9 +13459,21 @@ 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);
+                    this.currentFilePath = filePath;
+                    this.currentAST = ast;
+                    this.currentImports = importedModules;
                     const schema = this.processZodNode(declaration.init);
                     this.processingSchemas.delete(schemaName);
                     if (schema) {
@@ -13430,9 +13496,19 @@ 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);
+                  this.currentFilePath = filePath;
+                  this.currentAST = ast;
+                  this.currentImports = importedModules;
                   const schema = this.processZodNode(declaration.init);
                   this.processingSchemas.delete(schemaName);
                   if (schema) {
@@ -14164,7 +14240,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 +14252,9 @@ function collectAllExportedDefinitions(ast, typeDefinitions, currentFile, schema
         typeDefinitions[overrideId] = entry;
       }
     }
+    if (internalSchemaNames && extractInternalFlagFromComments(allComments)) {
+      internalSchemaNames.add(name);
+    }
   }
   resolvedTraverse(ast, {
     TSTypeAliasDeclaration: (path17) => {
@@ -14655,6 +14734,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 +14775,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 +14785,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 +14951,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);
@@ -16283,11 +16379,16 @@ var ResponseProcessor = class {
 var OperationProcessor = class {
   schemaProcessor;
   responseProcessor;
+  authPresets;
   performanceProfile;
-  constructor(schemaProcessor, responseProcessor, performanceProfile) {
+  constructor(schemaProcessor, responseProcessor, options = {}) {
     this.schemaProcessor = schemaProcessor;
     this.responseProcessor = responseProcessor;
-    this.performanceProfile = performanceProfile;
+    this.authPresets = {
+      ...DEFAULT_AUTH_PRESET_REPLACEMENTS,
+      ...options.authPresets
+    };
+    this.performanceProfile = options.performanceProfile;
   }
   processOperation(varName, routePath, dataTypes, pathParamNames = []) {
     const method = varName.toLowerCase();
@@ -16312,9 +16413,10 @@ var OperationProcessor = class {
       definition.deprecated = true;
     }
     if (explicitSecurity && explicitSecurity.length > 0) {
-      definition.security = explicitSecurity;
+      definition.security = explicitSecurity.map((req) => Object.fromEntries(Object.entries(req).map(([scheme, scopes]) => [this.applyPreset(scheme), scopes])));
     } else if (auth) {
-      const authItems = auth.split(",").map((item) => item.trim());
+      const mapped = performAuthPresetReplacements(auth, this.authPresets);
+      const authItems = mapped.split(",").map((item) => item.trim());
       definition.security = authItems.map((authItem) => ({
         [authItem]: []
       }));
@@ -16527,6 +16629,9 @@ ${suffix}`;
       response.links[link.name] = linkObject;
     }
   }
+  applyPreset(scheme) {
+    return this.authPresets[scheme.toLowerCase()] ?? scheme;
+  }
   createQuerystringParameter(dataTypes) {
     if (!dataTypes.querystringType) {
       return void 0;
@@ -16615,7 +16720,10 @@ var RouteProcessor = class {
       return new RegExp(`^${regexPattern}$`);
     });
     this.responseProcessor = new ResponseProcessor(this.config, this.schemaProcessor);
-    this.operationProcessor = new OperationProcessor(this.schemaProcessor, this.responseProcessor, this.performanceProfile);
+    this.operationProcessor = new OperationProcessor(this.schemaProcessor, this.responseProcessor, {
+      authPresets: this.config.authPresets,
+      performanceProfile: this.performanceProfile
+    });
   }
   processResponsesFromConfig(dataTypes, method) {
     return this.responseProcessor.processResponses(dataTypes, method);
@@ -16841,6 +16949,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 +17077,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.4.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",